1. 适用场景本草纲目中药查询 API 为开发者提供了一种便捷的方式将《本草纲目》及常见中药材的结构化信息集成到各类应用中。典型场景包括中医养生/食疗 App 的药材百科用户搜索“枸杞”“黄芪”等药材展示其气味、主治、附方等详情提升内容专业性。中药知识科普类小程序快速搭建药材目录配合模糊建议功能引导用户准确输入。AI 中医问诊辅助参考作为知识库的查询后端为智能对话提供内容支撑。古籍数字化与国学教育将传统中药知识以 API 形式输出方便用于教学课件或互动展示。该 API 采用简单的 GET 请求非常适合微服务架构或前端直接调用。2. 接口能力边界请求方式GET接口地址https://v1.apizero.cn/api/bencaoQPS 限制10 请求/秒满足大多数中小规模场景的实时查询需求。匹配模式支持精确匹配matchedexact和模糊建议。当输入名称无法精确匹配时返回 HTTP 4040 状态码并附带suggestions数组最多 10 个候选词方便前端做二次选择。数据覆盖涵盖《本草纲目》记载及常见中药材但不包含所有民间验方。返回字段包括药材名、释名、气味、主治、附方等以纯文本段落形式组织。注意数据来源于公开整理资料仅供学习参考不得作为医疗诊断依据。3. 请求参数与鉴权Query 参数msg参数类型必需说明示例msgstring是药材中文名称最长 50 字符。支持精确名称或部分模糊输入自动触发建议人参鉴权方式接口支持可选 API Key 鉴权通过 HTTP HeaderX-API-Key传递。未鉴权请求每日有 30 次体验额度以 IP 或设备标识为限。返回数据量与鉴权请求一致但超额后会收到限流错误。鉴权请求在 Header 中添加X-API-Key: {your_api_key}无每日频次限制但仍受全局 QPS 10/s 约束。建议生产环境始终携带 API Key避免因日常流量超出限额导致服务中断。4. 接入示例4.1 使用 curl 直接调试# 替换为你的 API Key可选 curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/bencao?msg人参若无需鉴权可省略-H行curl -sS -X GET https://v1.apizero.cn/api/bencao?msg甘草4.2 Python 封装示例import requests API_URL https://v1.apizero.cn/api/bencao API_KEY 你的API密钥 # 可选未鉴权则设为 None def query_herb(name: str) - dict: 查询药材详情自动处理精确匹配与模糊建议 headers {} if API_KEY: headers[X-API-Key] API_KEY params {msg: name} resp requests.get(API_URL, paramsparams, headersheaders, timeout10) if resp.status_code 200: return resp.json() elif resp.status_code 4040: return resp.json() # 包含 suggestions 数组 else: resp.raise_for_status() # 测试精确查询 result query_herb(丁香) print(result[data][name], result[data][matched]) # 输出: 丁香 exact # 测试模糊场景输入不存在组合 result query_herb(人参枸杞) if result.get(code) 0: print(精确结果, result[data][name]) else: print(建议, result[data].get(suggestions, []))5. 返回数据结构解读成功响应HTTP 200JSON 示例{ code: 0, msg: 成功, request_id: mqx8x12345abc, data: { name: 人参, matched: exact, detail: 「释名」黄参、神草、土精、血参...\n「气味」根甘、温、无毒...\n「主治」补五脏安精神... } }关键字段说明字段类型描述codeint业务状态码0 表示成功非 0 表示异常如 4040 表示未精确匹配msgstring提示信息如“成功”或“未找到匹配以下为建议”request_idstring请求唯一标识用于调试和日志追踪data.namestring药材名称data.matchedstring匹配类型exact精确匹配或suggest模糊建议data.detailstring药材详情以换行符分隔的多个段落包含释名、气味、主治、附方等data.suggestionsstring[]仅当 matched 为suggest时存在数组长度 ≤ 10为推荐药材名称注意data.detail为文本块未做结构化拆分开发者可根据自己的业务需求按\n分割或直接渲染。模糊匹配流程示意传入msg人参枸杞服务端未找到精确条目返回 HTTP 4040 code4040 data.suggestions [人参,枸杞,人参叶,...]客户端可展示建议列表让用户选择或自动重试匹配第一个建议。6. 常见错误与异常处理HTTP 状态码与业务含义状态码业务码常见原因处理建议2000正常返回精确或模糊根据matched字段区分40404040未精确匹配返回建议列表展示suggestions供用户选择400-参数错误如msg为空或超长检查msg长度 ≤ 50 字符且不为空401-API Key 无效或未提供但超额验证 API Key 合法性或等待次日额度过期未鉴权场景429-QPS 超限降低请求频率加入本地重试与退避逻辑代码级错误处理建议import time import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def query_herb_robust(name: str, max_retries: int 3): session requests.Session() retries Retry(totalmax_retries, backoff_factor1, status_forcelist[429, 500, 502, 503, 504]) session.mount(https://, HTTPAdapter(max_retriesretries)) headers {X-API-Key: API_KEY} if API_KEY else {} resp session.get(API_URL, params{msg: name}, headersheaders, timeout10) if resp.status_code in (200, 4040): return resp.json() else: raise Exception(fHTTP {resp.status_code}: {resp.text})7. 工程化注意事项7.1 缓存策略同一药材名称的返回内容基本不变数据源为静态文本建议使用本地缓存如 Redis 或内存字典减少重复调用。缓存 TTL 可设为 24 小时或更长。7.2 模糊匹配降级当接口返回 4040 suggestions 时客户端可自动尝试请求 suggestions 数组的第一个名称最高置信度候选。但注意不要无限递归可设定最多尝试 1 次。7.3 数据版权与引用返回的detail文本包含《本草纲目》原文章节商用场景需确认是否符合原始资料的使用协议。建议在展示时注明“内容整理自《本草纲目》及公开资料仅供参考”。7.4 限流与重试全局 QPS 10/s单应用部署时可在请求层做本地限速如令牌桶避免 429 错误。对于生产环境建议使用连接池并启用指数退避重试。7.5 部署位置由于接口仅支持国内中文名称若应用面向海外用户需注意网络延迟。考虑在靠近国内区域部署服务器或使用 CDN 反向代理若允许。8. 参考文档本草纲目·中药查询 API 文档https://apizero.cn/aidocs/bencao原始数据格式说明https://apizero.cn/aidocs/bencao/raw.md
