一、适用场景重述中药材知识查询接口/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 并格式化输出可配合jqcurl -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 顶层字段字段类型说明codeint0 表示成功非 0 表示错误msgstring人类可读的状态描述request_idstring请求唯一标识便于排查问题dataobject具体业务数据5.2 data 字段字段类型说明namestring查询的药材名称matchedstringexact精确匹配若为suggest则响应结构不同detailstring包含释名、气味、主治、附方等内容的纯文本以\n分隔4040 响应示例未命中时{ code: 4040, msg: 未找到相关药材以下为建议名称, data: { suggestions: [人参, 枸杞] } }此时suggestions数组包含最多 10 个候选名称客户端可展示给用户选择。六、常见错误与排查错误现象可能原因处理方式HTTP 401API 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原始文档Markdownhttps://apizero.cn/aidocs/bencao/raw.md