随机诗词API参数详解：type主题枚举与action调试实践
从参数视角理解随机诗词接口
调用第三方内容接口时，"能调通"通常只解决一部分问题，真正决定代码稳定性的往往是对参数的语义理解。随机诗词接口虽然结构简单，但 type 与 action 两个字段的组合方式、取值边界和优先级关系如果不搞清楚，很容易在联调阶段反复返工。这篇笔记不重复接口文档，而是把两个请求参数逐个拆开，结合 curl 与 Python 示例说明如何构造请求、解读返回，以及在生产环境落地的注意事项。
适用场景：先判断业务位置
随机诗词接口适合以下使用位置：
- 网站首页或内容频道的"每日一诗"模块，按日期或星期切换主题。
- 聊天机器人内的文本指令，用户指定"山水"或"节日"后返回对应诗词。
- 内部内容生产管线中的素材采集环节，先获取原始文本再由人工筛选。
- 教育类小程序课堂导入，按季节动态切换诗词主题。
不适合的场景包括对响应时间强敏感的高并发展示页，因为接口 QPS 为 5 次/秒，设计时需要考虑限速。另外，它不提供按作者、朝代或诗词长度筛选的能力，这类需求需要寻找其他数据源或本地词库。
接口能力边界
先明确这个接口能做什么、不能做什么：
- 请求方法：POST
- 请求地址：https://v1.apizero.cn/api/shici
- 主题筛选：支持 10 种类型，通过 type 参数传入。
- 类型查询：通过 action=types 获取全部主题标识列表，该操作不消耗调用额度。
- 速率限制：QPS 5 / 秒，超出后的具体表现以文档为准。
可以把接口理解为"按主题返回随机诗词的只读能力"。它不承诺返回结果不重复，也不提供分页或游标，每次调用都是一次独立的随机抽样。
请求参数详解
请求头与鉴权
所有请求使用 POST，并携带两个请求头：
- X-API-Key：访问密钥，建议通过环境变量 $APIZERO_API_KEY 引用，避免把密钥硬编码进代码仓库。
- Content-Type: application/json
请求体是一个 JSON 对象，最多包含两个字段：type 与 action，两者均可选。
type 字段：10 个主题枚举
type 是核心筛选参数，取值使用英文标识，与中文主题的对应关系如下：
| type 值 | 中文主题 |
|---|---|
| shuqing | 抒情 |
| siji | 四季 |
| shanshui | 山水 |
| tianqi | 天气 |
| renwu | 人物 |
| shenghuo | 生活 |
| jieri | 节日 |
| dongwu | 动物 |
| zhiwu | 植物 |
| shiwu | 食物 |
这个映射关系在写配置表或数据库字典时建议原样保留。原因有二：一是接口的枚举值不会因为前端展示文案变化而改变；二是如果自行改成拼音缩写或自定义编号，后续排查问题时需要额外维护一层翻译逻辑。
type 缺省时，接口在所有主题范围内随机返回一首诗词；显式传入 type 则缩小随机范围。注意 type 区分大小写，传 "ShanShui" 或 "TianQi" 都不会被识别，只能使用小写枚举值。
action 字段：调试与类型发现
action 当前只有一个可用取值：types。请求时携带 action=types，接口返回主题类型列表而不是诗词。这个能力有两个用途：
- 接入初期验证 API Key 是否有效，且不消耗调用额度。
- 在配置后台动态渲染主题筛选项，接口侧新增主题时客户端无需发版。
当 action 与 type 同时存在时，action 优先，可以理解为一种"调试模式"。实际开发时要注意：先请求 types 再请求诗词，两次请求共享同一个 QPS 配额。
参数组合规则
通过一个表格汇总不同参数组合的行为：
| type 值 | action 值 | 接口行为 |
|---|---|---|
| 空 | 空 | 全主题范围内随机返回一首诗词 |
| siji | 空 | 四季主题范围内随机返回一首诗词 |
| 空 | types | 返回全部主题类型列表 |
| siji | types | action 优先，返回主题类型列表 |
空值代表字段缺省或传空字符串。实际测试时，请求体传 {} 也能触发一次正常的随机诗词请求，这可以作为连通性检查的最小用例。
curl 接入示例
基础随机请求
把 API Key 存放在环境变量中，避免密钥出现在命令行历史里：
export APIZERO_API_KEY="your-key-here" curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://v1.apizero.cn/api/shici"按主题筛选
指定 theme 类型为四季：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type": "siji"}' \ "https://v1.apizero.cn/api/shici"获取类型列表
请求 action=types 拿到主题枚举清单：
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "types"}' \ "https://v1.apizero.cn/api/shici"三个示例覆盖了参数组合表中的三类核心行为。注意 -d 参数里的 JSON 保持单行即可，不需要额外的转义；如果使用 Windows CMD，引号规则需要做相应调整。
Python 代码接入
生产环境更常见的做法是用编程语言封装。以下使用 requests 库做一个最小封装，重点是把 type 与 action 参数从配置中解析出来：
import json import os import requests API_URL = "https://v1.apizero.cn/api/shici" API_KEY = os.environ["APIZERO_API_KEY"] HEADERS = { "X-API-Key": API_KEY, "Content-Type": "application/json", } def fetch_poem(poem_type: str | None = None, action: str | None = None) -> dict: payload = {} if poem_type: payload["type"] = poem_type if action: payload["action"] = action resp = requests.post(API_URL, headers=HEADERS, json=payload, timeout=8) resp.raise_for_status() return resp.json() if __name__ == "__main__": # 获取类型列表，用于校验 API Key print(json.dumps(fetch_poem(action="types"), ensure_ascii=False, indent=2)) # 获取山水主题诗词 print(json.dumps(fetch_poem(poem_type="shanshui"), ensure_ascii=False, indent=2))这段代码做了一件关键的事情：只在参数有值时才放入 payload，避免出现 {"type": null} 或 {"action": ""} 这类无效字段。在 Python 3.10+ 环境中，str | None 类型注解可以正常工作；更早版本请改用 Optional[str]。
返回字段解读
响应体是标准 JSON 结构，基础框架如下：
{ "code": 200, "data": {}, "message": "success" }三个字段的含义：
| 字段 | 类型 | 含义 |
|---|---|---|
| code | number | 业务状态码，200 表示成功 |
| data | object | 具体返回数据，结构随请求参数变化 |
| message | string | 可读的状态说明 |
data 内部的具体字段（例如诗词标题、作者、正文等）未在公开示例中完整列出，实际开发时应以文档为准，建议先写一段"字段探测"代码确认原始结构：
raw = fetch_poem(poem_type="shanshui") print(json.dumps(raw, ensure_ascii=False, indent=2))拿到真实返回后，再把 data 中的字段收敛到数据类或常量字典中，避免在业务代码里散落魔法字符串。对于 action=types 的请求，data 中通常是一个主题标识列表，可以直接用于渲染下拉框。
常见错误与排查切入点
401 鉴权失败
- 确认 X-API-Key 请求头的名称拼写，注意大小写。
- 确认环境变量已正确 export，并且当前 shell 会话未过期。
- 检查代码中是否使用了单引号包裹变量，导致未做变量展开。
400 参数错误
- 检查 type 是否传入了不存在的枚举值，如 zuowu、renwen。
- 检查 JSON 格式是否合法，手工拼接请求体时最容易出现多余逗号或引号不配对。
- 确认请求方法是否为 POST，一旦误用 GET 会被拒绝。
429 频率受限
- QPS 为 5 / 秒，是全局共享配额，假设自己不是唯一调用方。业务代码中的并发请求数应控制在 1～2 个以内。
- 检查是否在循环中连续调用而没有 sleep。例如批量拉取 50 首诗词时，需要显式加入间隔。
响应超时
- 第三方接口存在网络抖动，客户端应设置 5～10 秒的连接超时。
工程化注意事项
把接口接入生产环境时，建议在以下四个方向多花时间：
1. 主题枚举本地化
把 type 的 10 个枚举值同步到前端下拉框或后端配置表，并配上中文文案。接口新增主题时，通过 action=types 做一次全量比对，自动发现差异并告警。
2. 对随机性建立正确预期
既然是随机接口，两次请求返回相同内容的情况必然存在。若要保证展示不重复，需要在本地维护最近 N 首诗词的特征值（如标题 + 作者），做去重过滤。
3. 缓存与降级策略
"每日一诗"这类场景对实时性要求不高，可以在服务端按主题缓存 24 小时，只保留一首。若接口不可用，用本地静态诗词兜底，保证页面不空白。
4. 集中式配额保护
由于 QPS 限制是接口级的，建议在网关或调用层统一做限流，而不是让每个业务模块各自直接发起请求。这样做的另一个好处是：当接口升级或迁移时，只需要改一处调用地址。
参考文档
- 文档页：https://apizero.cn/aidocs/shici
- 原始文档：https://apizero.cn/aidocs/shici/raw.md
