本草纲目中药查询 API 实战：从参数设计到模糊匹配异常处理

1. 适用场景

本草纲目中药查询 API 为开发者提供了一种便捷的方式，将《本草纲目》及常见中药材的结构化信息集成到各类应用中。典型场景包括：

• 中医养生/食疗 App 的药材百科：用户搜索“枸杞”“黄芪”等药材，展示其气味、主治、附方等详情，提升内容专业性。
• 中药知识科普类小程序：快速搭建药材目录，配合模糊建议功能引导用户准确输入。
• AI 中医问诊辅助参考：作为知识库的查询后端，为智能对话提供内容支撑。
• 古籍数字化与国学教育：将传统中药知识以 API 形式输出，方便用于教学课件或互动展示。

该 API 采用简单的 GET 请求，非常适合微服务架构或前端直接调用。

2. 接口能力边界

• 请求方式：GET
• 接口地址：https://v1.apizero.cn/api/bencao
• QPS 限制：10 请求/秒，满足大多数中小规模场景的实时查询需求。
• 匹配模式：支持精确匹配（matched=exact）和模糊建议。当输入名称无法精确匹配时，返回 HTTP 4040 状态码并附带suggestions数组（最多 10 个候选词），方便前端做二次选择。
• 数据覆盖：涵盖《本草纲目》记载及常见中药材，但不包含所有民间验方。返回字段包括药材名、释名、气味、主治、附方等，以纯文本段落形式组织。

注意：数据来源于公开整理资料，仅供学习参考，不得作为医疗诊断依据。

3. 请求参数与鉴权

Query 参数msg

鉴权方式

接口支持可选 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, params=params, headers=headers, timeout=10) 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 200）JSON 示例：

{ "code": 0, "msg": "成功", "request_id": "mqx8x12345abc", "data": { "name": "人参", "matched": "exact", "detail": "「释名」黄参、神草、土精、血参...\n「气味」（根）甘、温、无毒...\n「主治」补五脏，安精神..." } }

关键字段说明

注意：data.detail为文本块，未做结构化拆分，开发者可根据自己的业务需求按\n分割或直接渲染。

模糊匹配流程示意

1. 传入msg=人参枸杞
2. 服务端未找到精确条目，返回 HTTP 4040 + code=4040 + data.suggestions =["人参","枸杞","人参叶",...]
3. 客户端可展示建议列表让用户选择，或自动重试匹配第一个建议。

6. 常见错误与异常处理

HTTP 状态码与业务含义

代码级错误处理建议

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(total=max_retries, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504]) session.mount("https://", HTTPAdapter(max_retries=retries)) headers = {"X-API-Key": API_KEY} if API_KEY else {} resp = session.get(API_URL, params={"msg": name}, headers=headers, timeout=10) if resp.status_code in (200, 4040): return resp.json() else: raise Exception(f"HTTP {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