一、适用场景重述
中药材知识查询接口（/api/bencao）提供了基于《本草纲目》及公开整理资料的结构化查询能力。常见的使用场景包括：
- 中医养生 App 中的药材百科模块：用户通过搜索框输入药材名称（如“当归”“枸杞”）即可获取释名、气味、主治、附方信息。
- 中药知识科普类小程序：将接口返回的正文内容渲染为卡片或富文本，辅助用户快速了解单味药。
- 古籍数字化项目中的引用检索：在数字化文档中通过药材名关联接口，快速定位原文记载。
- AI 问诊辅助参考：作为知识库的补充来源，为症状‑药材关联提供数据支撑。
注意：接口数据仅来自公开整理资料，不能替代专业医师诊断，任何医疗决策需遵医嘱。
二、接口能力边界分析
2.1 数据覆盖范围
接口覆盖的药材范围包括《本草纲目》中记载的常见品种，以及网络公开整理的其他中药材。从实践测试看，对于单味常用药（如人参、甘草、丁香、黄连、黄芩、茯苓）返回内容完整；对于冷僻或现代命名不统一的药材，可能存在缺漏。
已知局限：
- 不支持复方或成药查询（如“六味地黄丸”直接查询无结果，返回 4040 并建议单味药）。
- 药材别名覆盖面有限（例如“怀牛膝”可能回“牛膝”的相关建议，但不保证直接命中）。
- 释文内容为纯文本，不包含图片、炮制方法、配伍禁忌等结构化字段。
2.2 匹配机制与边界
接口的匹配逻辑分为两类：
| 匹配类型 | 条件 | 响应特征 |
|---|---|---|
| 精确匹配（exact） | 输入的msg与库中的标准名称完全一致 | matched: "exact"，返回完整详情 |
| 模糊匹配（suggest） | 输入名称不在库中但存在相似条目 | HTTP 状态码 4040（非标准 404），响应体包含suggestions数组（最多 10 项） |
边界示例：
msg=人参→ 精确匹配，直接返回详情。msg=人参枸杞→ 无精确匹配，返回 4040 并推荐["人参","枸杞"]等单味药。msg=美国西洋参→ 可能匹配到“西洋参”或返回空建议，取决于词库切分粒度。
注意：模糊匹配仅做表面分词或字符串相似度，不保证排序相关性，建议在客户端对建议列表做二次筛选。
2.3 并发与频率限制
官方文档标称 QPS 为10 次/秒（以实际文档为准）。若未使用 API Key，每天最多 30 次体验。超出后接口会返回HTTP 401或402类错误（具体以实际响应为准）。
对生产环境建议：
- 使用 API Key 提升配额，并在客户端实施本地缓存策略，避免重复请求相同药材。
- 对高频调用做令牌桶限流，避免瞬间打满 QPS 导致返回
429 Too Many Requests。
三、请求参数与鉴权
3.1 Query 参数
| 参数 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
msg | 是 | string | 药材名称，最长 50 字符，必须为中文 | 人参 |
3.2 Header 鉴权（可选）
| 字段 | 说明 |
|---|---|
Authorization | 格式为Bearer <your_api_key>，或使用X-API-Key头传递 |
不传 API Key 时依然可用（每日 30 次体验），但建议在生产环境中始终携带 Key 以获得稳定配额。
四、curl 接入示例
以下示例展示了携带 API Key 的完整请求方式（请将$APIZERO_API_KEY替换为真实 Key 或删除该头）：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/bencao?msg=甘草"无 Key 的简化请求（用于测试）：
curl -sS "https://v1.apizero.cn/api/bencao?msg=丁香"若希望接收标准格式 JSON 并格式化输出，可配合jq：
curl -sS "https://v1.apizero.cn/api/bencao?msg=当归" | jq .五、返回值字段解读
成功响应（HTTP 200）的 JSON 结构如下：
{ "code": 0, "msg": "成功", "request_id": "mqx8x12345abc", "data": { "name": "甘草", "matched": "exact", "detail": "「释名」美草、密甘、蜜草、国老……\n「气味」甘、平、无毒……\n「主治」五脏六腑寒热邪气，坚筋骨……" } }5.1 顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 0 表示成功，非 0 表示错误 |
msg | string | 人类可读的状态描述 |
request_id | string | 请求唯一标识，便于排查问题 |
data | object | 具体业务数据 |
5.2 data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 查询的药材名称 |
matched | string | "exact"精确匹配；若为"suggest"则响应结构不同 |
detail | string | 包含释名、气味、主治、附方等内容的纯文本，以\n分隔 |
4040 响应示例（未命中时）：
{ "code": 4040, "msg": "未找到相关药材，以下为建议名称", "data": { "suggestions": ["人参", "枸杞"] } }此时suggestions数组包含最多 10 个候选名称，客户端可展示给用户选择。
六、常见错误与排查
| 错误现象 | 可能原因 | 处理方式 |
|---|---|---|
| HTTP 401 | API Key 过期或无效 | 检查请求头中的 Key 是否正确，或重新生成 |
| HTTP 4040 | 输入名称不在库中 | 读取响应中的suggestions提供用户选择 |
| HTTP 429 | 超出 QPS | 降低请求频率，或升级配额 |
msg为空或非中文 | 参数校验失败 | 确保msg是 ≤50 字符的中文字符串 |
| 返回 500 | 服务端异常 | 稍后重试，并检查request_id提供给技术支持 |
调试技巧：在本地开发时，先通过浏览器直接访问https://v1.apizero.cn/api/bencao?msg=人参来验证网络连通性。
七、工程化注意事项
7.1 缓存策略
由于药材数据极少变更（古籍为固定内容），建议在服务端或客户端建立本地缓存，如使用 Redis 或 Map 存储已查过的药材详情，缓存 TTL 可设为 24 小时。这样能显著降低 QPS 压力并加快响应速度。
7.2 模糊匹配的二次确认
当接口返回suggestions时，不应直接使用第一个建议。可在 UI 上提供下拉列表供用户选择，或采用最长子串匹配算法从建议中挑选最接近项。
7.3 文本渲染优化
detail内容中包含以\n分隔的多段信息（如释名、气味、主治），建议客户端按章节拆分为数组，并使用 Markdown 或 HTML 渲染为有序区块，提升可读性。
7.4 错误重试与降级
网络不稳定时，对 500/502 类错误可采用指数退避策略重试（如间隔 1s、2s、4s）。同时准备一份内置的常见药材摘要（如 30 味高频药）作为降级数据，保障用户体验。
八、参考文档
- 接口文档：https://apizero.cn/aidocs/bencao
- 原始文档（Markdown）：https://apizero.cn/aidocs/bencao/raw.md
