QQ信息API实战：从号码校验到头像直链的分层接入设计
适用场景：把 QQ 号变成可展示的用户信息
在很多社区、内部工具或客服后台里，用户会直接粘贴一串 QQ 号，比如88888888。运营同学需要看到这个号码对应的昵称、头像、邮箱和空间链接，以便快速识别身份。手动打开腾讯相关页面逐个查询效率很低，而且头像要适配列表、详情页、放大图等不同尺寸，切图维护复杂度也不小。
QQ 信息接口解决的就是这个需求：输入一个 5-11 位纯数字 QQ 号，返回昵称、QQ 邮箱、QQ 空间链接，以及四个固定尺寸的头像直链 URL。前端拿到data.avatars对象后，直接用s40做列表缩略图、s100做评论头像、s140做详情页主图、s640做原图预览，不需要自己裁剪和存储。
接口能力边界
在接入前先明确该接口能做什么、不能做什么，避免后续返工。
| 能力 | 说明 |
|---|---|
| 查询内容 | 昵称、QQ 邮箱、QQ 空间链接、四个尺寸头像直链 |
| 号码校验 | 严格 5-11 位纯数字，防上游字符串截断引起号码错位 |
| 结果判定 | 返回is_found字段区分是否查询到用户 |
| 编码处理 | 上游输出 GBK 含中文昵称时自动转 UTF-8 |
| 流量限制 | QPS 10 / s，超出后需要排队或退避 |
接口不支持传入非纯数字参数，也不支持批量查询。如果需要处理多个 QQ 号，需要调用方自行做循环和并发控制。
请求参数与鉴权
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | 是 | 5-11 位 QQ 号码，纯数字 |
请求地址为：
https://v1.apizero.cn/api/qq?qq=88888888Header 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Authorization | string | 否 | API Key 鉴权头，格式Bearer sk_live_xxx；匿名调用时可省略 |
文档提供的 curl 示例中使用的是X-API-Key头，两种方式请以最终文档页为准。开发环境下先用匿名方式调试，上线前再把 Key 注入到环境变量中。
可复制的 curl 示例
最简单的一次请求如下：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/qq?qq=10001"如果使用 Authorization 头，等价写法为：
curl -sS \ -X GET \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxx" \ "https://v1.apizero.cn/api/qq?qq=10001"响应是 JSON 数组结构，第一个元素包含业务状态和内容。为了便于在 shell 里快速看结果，可以接jq：
curl -sS \ -X GET \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxx" \ "https://v1.apizero.cn/api/qq?qq=10001" | jq '.[0].example.data'返回字段详解
以文档中的成功响应为例：
[ { "content_type": "application/json", "description": "成功", "example": { "code": 0, "data": { "avatars": { "s100": "https://q1.qlogo.cn/g?b=qq&nk=88888888&s=100", "s140": "https://q1.qlogo.cn/g?b=qq&nk=88888888&s=140", "s40": "https://q1.qlogo.cn/g?b=qq&nk=88888888&s=40", "s640": "https://q1.qlogo.cn/g?b=qq&nk=88888888&s=640" }, "is_found": true, "mail": "88888888@qq.com", "name": "腾讯客服", "qq": "88888888", "qzone": "https://user.qzone.qq.com/88888888" }, "msg": "成功", "request_id": "abc123def456" }, "status": "200" } ]核心字段说明如下：
| 字段 | 类型 | 含义 |
|---|---|---|
code | number | 业务状态码，0 表示成功 |
msg | string | 状态描述 |
request_id | string | 请求唯一标识，可用于日志追踪 |
data.qq | string | 回显的 QQ 号 |
data.name | string | 查询到的昵称，可能为 null |
data.mail | string | 对应 QQ 邮箱 |
data.qzone | string | QQ 空间链接 |
data.is_found | boolean | 是否成功查询到用户 |
data.avatars | object | 四个尺寸的头像直链 URL |
注意is_found才是判断查询是否成功的关键。当号码未准备或未开放展示时，name、mail等字段可能缺失，但接口仍可能返回 HTTP 200，所以业务代码里不能只检查code。
常见错误与排查思路
1. QQ 号位数不对
接口要求 5-11 位纯数字。如果用户输入1234或123456789012，建议在调用前置校验并直接提示，避免把无效请求发到上游。
2. 返回结果中is_found为 false
一种情况是号码确实不存在，另一种情况是安全增强机制生效：上游返回的 QQ key 与请求不一致时，接口会视为未查询到。此时应优先检查请求参数是否被 URL 编码或中间层改写。
3. 昵称乱码
腾讯历史接口在部分场景下输出 GBK 编码，接口已做自动转 UTF-8 兜底。若发现个别昵称仍异常，先确认返回的content_type是否被网关改写，再检查自己是否对响应做了二次解码。
4. 鉴权失败
检查 Header 名称和值格式。Bearer后必须有一个空格，Key 不能包含换行符。匿名调用有限额，超出后需要配置 API Key。
5. 频率超限
QPS 为 10 / s，批量场景下建议把并发数压到 5 以下，并加入指数退避重试，避免瞬间打满。
工程化注意事项
这一节重点说接入生产系统时的几个细节问题。
前置参数校验
虽然接口本身做了严格校验，但提前在应用层拦截无效输入可以减少无谓的网络开销。推荐用正则：
fn is_valid_qq(s: &str) -> bool { let len = s.len(); len >= 5 && len <= 11 && s.chars().all(|c| c.is_ascii_digit()) }对于 Rust/Go/Node 不同后端，重点是判断长度后逐字节确认纯数字，避免01234这类带前导零的字符串被整型转换吞掉。
头像 URL 直接透传还是二次存储
avatars返回的是腾讯 CDN 直链，可以直接放到<img src>里。建议前端做错误兜底：
<img src="" >qq=10001 request_id=abc123def456 code=0 is_found=true cost_ms=42这样可以快速定位是业务侧参数问题、上游超时还是鉴权失效。
错误响应兼容
上游可能出现两种响应形态：正常是portraitCallBack(...)，异常是_Callback({error:...})。接口已经自动识别并归一化，调用方无需处理。但如果通过全链路压测观察异常率，建议关注status字段为 200 但code非 0 的响应，这类不会触发 HTTP 层告警。
参考文档
- 接口文档：https://apizero.cn/aidocs/qq
- 原始 Markdown：https://apizero.cn/aidocs/qq/raw.md