谜语大全 API 参数详解与请求优化最佳实践
适用场景
谜语大全 API 适用于需要集成中文谜语内容的应用程序，例如：
- 社交聊天机器人中的趣味互动模块
- 每日谜语推送或谜语小游戏
- 教育类 App 中的益智练习
- 内容运营中自动生成谜语素材
该接口提供三种操作模式：随机返回一条谜语（random）、按类型分页列表（list）以及查询所有可用类型（types），覆盖了绝大多数对谜语数据的获取需求。
接口能力边界
- 请求方法：POST（请注意不是 GET）
- 请求地址：
https://v1.apizero.cn/api/riddle - QPS 限制：5 次 / 秒，单应用需做好并发控制与本地缓存
- 鉴权方式：请求头
X-API-Key，需替换为有效密钥 - 数据格式：请求体与响应均为 JSON
接口不提供模糊搜索或自定义谜语创建功能，仅支持预先定义好的谜语库，使用前应通过types模式确认可用的谜语类型，避免传参错误。
请求参数详解
请求体为 JSON 对象，包含三个可选字段，具体说明如下：
| 参数名 | 类型 | 必填 | 描述 | 默认值 | 可选值 |
|---|---|---|---|---|---|
action | string | 否 | 操作模式 | random | random,list,types |
type | string | 否（仅 list 模式可用） | 谜语类型（小写字母） | 无 | 通过types获取，例如dongwu（动物） |
page | string | 否（仅 list 模式可用） | 页码 | 1 | 正整数（建议作为字符串传入） |
action 参数
- random：返回单条随机谜语，忽略
type和page。适合每次调用获取一条新谜语。 - list：返回分页列表，可配合
type和page使用。若type为空，则返回所有类型的谜语列表。 - types：返回所有谜语类型的列表及对应数量。该模式不消耗
list的 QPS，建议在应用启动时调用一次并缓存结果。
type 参数（list 模式专用）
仅在action=list时有效。值必须从types返回的type_slug中获取（均为小写字母）。建议先调用types模式获取可用类型列表，再构建类型筛选请求。
page 参数（list 模式专用）
page以字符串形式传入，如"1"，表示第 1 页。实际每页条数由服务端固定（通常为 10 条，以文档为准），无法自定义。若传入非数字或超出总页数，服务端可能返回空列表或 400 错误。
鉴权与请求头
所有请求均需在 HTTP 头部携带 API 密钥：
X-API-Key: 你的密钥 Content-Type: application/json密钥通过 API 管理后台获取，请妥善保管，避免泄露。生产环境中建议将密钥存储在环境变量或密钥管理服务中，不要硬编码在代码里。
curl 请求示例
示例 1：随机获取一条谜语
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "random"}' \ "https://v1.apizero.cn/api/riddle"示例 2：获取第 2 页的类型为“动物”的谜语列表
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "list", "type": "dongwu", "page": "2"}' \ "https://v1.apizero.cn/api/riddle"示例 3：查询所有可用谜语类型
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "types"}' \ "https://v1.apizero.cn/api/riddle"注意：请将$APIZERO_API_KEY替换为你的真实密钥。密钥不要在公共网络传输，建议在本地环境变量中设置。
响应字段解读
响应 JSON 结构固定：
{ "code": 200, "data": {}, "message": "success" }| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码，200 表示成功，其他表示错误 |
data | object | 具体数据，结构随 action 变化 |
message | string | 提示信息，成功时为 "success" |
random 模式下的 data 结构
{ "id": 123, "question": "什么动物天天熬夜？", "answer": "熊猫，因为它有黑眼圈", "type": "dongwu", "type_name": "动物" }id: 谜语唯一标识question: 谜面answer: 谜底type: 类型 slug（小写字母）type_name: 类型中文名
list 模式下的 data 结构
{ "total": 50, "page": 1, "total_pages": 5, "list": [ { "id": 1, "question": "...", "answer": "...", "type": "...", "type_name": "..." } ] }total: 符合条件的谜语总数page: 当前页码total_pages: 总页数list: 本次返回的谜语数组
types 模式下的 data 结构
{ "list": [ { "type": "dongwu", "type_name": "动物", "count": 20 }, { "type": "zhiwu", "type_name": "植物", "count": 15 } ] }type: 类型 slugtype_name: 类型中文名count: 该类型的谜语数量
常见错误与调试
400 Bad Request
可能原因：
action参数值拼写错误（如"randem"）type值未从types接口获取，使用了未定义的类型page参数为负数或非数字字符串（如"abc"）- JSON 格式非法（如多余逗号、引号不匹配）
排查建议：使用jq工具验证 JSON 格式：echo '{"action":"list","type":"dongwu","page":"1"}' | jq .
401 Unauthorized
- 缺少
X-API-Key头 - 密钥无效或已过期
429 Too Many Requests
- 超过 QPS 5 次/秒的限制
- 建议在客户端实现指数退避重试，或使用本地缓存减少请求频率
500 Internal Server Error
- 服务端内部问题，可稍后重试，若持续出现需联系平台技术支持
工程化注意事项
1. 合理使用 types 模式缓存类型列表
在应用启动时调用一次types模式，将类型列表缓存到本地（如 Redis 或内存），避免每次列表请求都重复获取类型定义。类型列表更新频率极低，缓存有效期可设为 1 天。
2. 分页列表的总页数获取
list响应中包含total_pages，前端可根据此值动态生成翻页控件。注意第一次加载时先获取第 1 页，即可获取总页数。
3. 随机谜语与列表查询的 QPS 共池
random和list模式共享同一个 QPS 池（5 次/秒），若需要频繁随机获取谜语，建议预先拉取一批谜语缓存到本地，然后从本地随机选取，减少 API 调用。
4. 错误重试策略
对于 429 和 500 错误，建议实现指数退避重试：初次等待 1 秒，后续加倍，最多重试 3 次。对于 400 和 401 错误，应记录日志并提示开发者检查参数或密钥，不应重试。
5. 密钥管理与安全
- 不要在客户端代码中硬编码 API Key
- 在服务端使用环境变量或配置中心加载
- 定期轮换密钥，并监控异常调用
6. 接口限流与降级
如果业务需要高频使用，建议添加本地缓存层。例如：每小时拉取一次全量谜语列表（通过设置page从 1 到total_pages循环请求，但需注意 QPS 限制），然后本地存储所有谜语，后续全部从本地读取。
参考文档
- 谜语大全 API 文档
- 原始 Markdown 文档