本草纲目中药查询 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`

参数	类型	必需	说明	示例
msg	string	是	药材中文名称，最长 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, 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「主治」补五脏，安精神..." } }

关键字段说明

字段	类型	描述
code	int	业务状态码，0 表示成功；非 0 表示异常（如 4040 表示未精确匹配）
msg	string	提示信息，如“成功”或“未找到匹配，以下为建议”
request_id	string	请求唯一标识，用于调试和日志追踪
data.name	string	药材名称
data.matched	string	匹配类型：`exact`（精确匹配）或`suggest`（模糊建议）
data.detail	string	药材详情，以换行符分隔的多个段落，包含释名、气味、主治、附方等
data.suggestions	string[]	仅当 matched 为`suggest`时存在，数组长度 ≤ 10，为推荐药材名称

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

模糊匹配流程示意

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

6. 常见错误与异常处理

HTTP 状态码与业务含义

状态码	业务码	常见原因	处理建议
200	0	正常返回（精确或模糊）	根据`matched`字段区分
4040	4040	未精确匹配，返回建议列表	展示`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(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}")