从 curl 到工程封装：访问量计数器API集成实战-育师

适用场景

当你在 GitHub 仓库 README、个人博客或 SaaS 产品页面上需要展示“本页浏览次数”时，传统做法是自建数据库+后端接口，维护复杂度高且部署复杂。访问量计数器 API 提供了一种即插即用的方案：通过一个 GET 请求即可输出 SVG 图片或 JSON 数据，支持按站点、按页面隔离计数，并且提供多套动效主题（像素角色举牌、渐变文字等），可直接用<img>标签嵌入 Markdown。

常见使用场景：

GitHub 项目 README 中展示项目总访问量。
静态博客每条文章页脚显示当日/累计阅读量。
管理后台统计落地页曝光（配合 JSON 格式自行渲染图表）。

接口能力边界

该接口按站点（site）和名称（name）两个维度隔离计数。同一站点下可挂多个计数器（如首页、产品页、文章页），不同站点之间的计数互不干扰。计数模式支持每日清零（daily）和累计不清零（total），满足短期活动统计与长期总览需求。

输出格式丰富：

SVG：返回可直接嵌入网页的矢量图，包含动画效果（像素角色帧动画或渐变 SVG）。
PNG：静态位图，适合邮件或 PDF 等不支持 SVG 的场景。
JSON：原始结构化数据，便于前端自行渲染或存入数据库。

接口 QPS 限制为 10/s，日常集成足够。注意：每次计数模式下的访问都会增加计数，除非指定no_increment=1做只读查询。

参数与鉴权

鉴权方式

使用 HTTP HeaderX-API-Key传递密钥。你需要在 apizero.cn 准备后获取 API Key，并在请求中携带。

Query 参数一览

参数	必填	类型	说明	示例
`site`	否	string	站点标识（建议传你的域名）。不传时全局共享计数器。	`apizero.cn`
`name`	否	string	计数器名称，同一站点下可不同。默认`demo`。	`home`
`mode`	否	string	计数模式：`daily`/`total`。默认`daily`。	`total`
`theme`	否	string	主题，详见文档。默认`gojo_board`（像素牌）。	`sukuna_mark`
`format`	否	string	输出格式：`svg`/`png`/`json`。默认`svg`。	`json`
`length`	否	number	显示位数，4~12，默认 7（前导补零）。	`7`
`no_increment`	否	number	只读模式：`1`不递增计数，`0`递增。默认`0`。	`1`

所有参数均以文档 apizero.cn/aidocs/visits-counter 为准。

curl 接入示例

以下命令可获取apizero.cn站点、home计数器的 JSON 格式数据，并递增计数（默认daily模式）：

curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/visits-counter?site=apizero.cn&name=home&format=json"

若要获取 SVG 图像并保存为文件：

curl -sS -o counter.svg \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/visits-counter?site=myblog.com&name=article-001&mode=total&theme=seal_blue"

只查询不递增（预览）：

curl -sS \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/visits-counter?site=preview&name=test&no_increment=1&format=json"

请将YOUR_API_KEY替换为你实际的密钥。

返回值解读

当请求format=json时，响应体是一个数组，首个元素包含完整数据。以下为示例 JSON 的字段说明：

{ "code": "200", "data": { "display_value": "0000042", "format": "json", "incremented": true, "length": 7, "mode": "daily", "name": "home", "record": { "daily": 42, "day": "2026-05-09", "total": 1024, "updated_at": "2026-05-09T21:48:52+08:00" }, "step": 1, "theme": "gojo_board", "theme_name": "像素牌-苍空", "value": 42 }, "desc": "success", "tips": "极数本源 · https://apizero.cn" }

主要字段含义：

字段	类型	说明
`code`	string	业务状态码，`200`表示成功。
`data.value`	number	当前计数（根据 mode 为日值或累计值）。
`data.display_value`	string	补齐前导零后的显示字符串，可直接拼接 SVG 显示。
`data.incremented`	boolean	本次请求是否执行了递增操作。若`no_increment=1`则为 false。
`data.mode`	string	请求时的计数模式。
`data.record`	object	明细记录，包含 daily（当日值）、total（累计值）、day（当前日期）、updated_at（最后更新时间）。
`data.step`	number	每次递增步长，固定 1。
`data.theme_name`	string	当前主题的中文名称。

当输出格式为svg或png时，响应体直接为二进制内容，需设置相应的 Content-Type（例如image/svg+xml或image/png），可在浏览器或<img>标签中直接引用 URL（但需注意 API Key 不宜暴露在前端）。

常见错误排查

错误现象	可能原因	解决方案
返回 HTTP 401	API Key 未传或无效	在请求头中添加`X-API-Key`，并确认密钥正确。
返回 HTTP 400	必填参数缺失或参数值不合法（如长度超出范围、theme 名称拼写错误）	对照文档检查参数。
返回`code`非`200`	业务逻辑错误，例如`no_increment`传了非 0/1 的值	检查参数类型和取值范围。
SVG 显示异常（乱码）	未正确设置 Content-Type 或未按图片格式处理	若用`<img>`标签，可直接引用 API URL（带上认证参数，但注意安全性）。
计数未预期递增	可能误将`no_increment`设为了`1`，或每次请求使用了不同参数导致创建了多个计数器	排查参数一致性，确认在相同 site 和 name 下调用。
QPS 超限	短时间内请求频率超过 10/s	加入本地缓存或节流，不要在前端直接并发请求。

工程化注意事项

1. 环境变量管理 API Key

不要在代码中硬编码 API Key。建议通过环境变量读取：

export APIZERO_API_KEY="你的密钥"

在 Node.js 中：

const apiKey = process.env.APIZERO_API_KEY;

Python：

import os api_key = os.environ.get("APIZERO_API_KEY")

2. 服务端封装（避免暴露密钥）

由于 API Key 要求放在请求头中，若直接在前端<img>标签或fetch中携带密钥，会泄漏到浏览器的开发者工具或网络日志中。推荐在服务端进行代理封装：

客户端 -> 你的后端（持有 API Key） -> 访问量计数器 API。

例如使用 Express 封装一个接口：

app.get('/api/counter', async (req, res) => { const { site, name, mode, theme } = req.query; const apiRes = await fetch('https://v1.apizero.cn/api/visits-counter?' + new URLSearchParams({ site: site || 'default', name: name || 'default', mode: mode || 'daily', theme: theme || 'gojo_board', format: 'svg' }), { headers: { 'X-API-Key': process.env.APIZERO_API_KEY } }); const svg = await apiRes.text(); res.set('Content-Type', 'image/svg+xml'); res.send(svg); });

这样前端只需引用/api/counter?site=xxx即可，密钥存在于后端。