谜语大全 API 参数详解与请求优化最佳实践

适用场景

谜语大全 API 适用于需要集成中文谜语内容的应用程序，例如：

• 社交聊天机器人中的趣味互动模块
• 每日谜语推送或谜语小游戏
• 教育类 App 中的益智练习
• 内容运营中自动生成谜语素材

该接口提供三种操作模式：随机返回一条谜语（random）、按类型分页列表（list）以及查询所有可用类型（types），覆盖了绝大多数对谜语数据的获取需求。

接口能力边界

• 请求方法：POST（请注意不是 GET）
• 请求地址：https://v1.apizero.cn/api/riddle
• QPS 限制：5 次 / 秒，单应用需做好并发控制与本地缓存
• 鉴权方式：请求头X-API-Key，需替换为有效密钥
• 数据格式：请求体与响应均为 JSON

接口不提供模糊搜索或自定义谜语创建功能，仅支持预先定义好的谜语库，使用前应通过types模式确认可用的谜语类型，避免传参错误。

请求参数详解

请求体为 JSON 对象，包含三个可选字段，具体说明如下：

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" }

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: 类型 slug
• type_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 文档