企业官网建设流程全解析

一、接口概述与适用场景

本草纲目·中药查询接口（/api/bencao）提供基于《本草纲目》及常见中药材的查询能力。输入药材中文名称（如“人参”“甘草”），返回该药材的释名、气味、主治、附方等详细文本。数据经过整理，便于开发者快速集成到中医养生App、中药知识科普小程序、AI问诊辅助、古籍数字化或国学教学系统中。

接口采用标准 RESTful 设计，QPS 限制为 10 次/秒，适合中小规模调用。注意：数据仅供学习参考，实际用药请遵医嘱。

二、接口能力边界

• 精确匹配：输入完整药材名称，返回matched: "exact"的详情。
• 模糊匹配：若名称不存在，返回 HTTP 4040 状态码，并附带suggestions数组（最多 10 条相关药材）。例如查询“人参枸杞”会建议“人参”“枸杞”等单味药。
• 字段限制：msg参数最长 50 个字符，仅支持中文。
• 鉴权方式：可选 API Key（通过X-API-Key请求头传递）。未携带 Key 时每日允许 30 次调用，超出后返回鉴权错误。

三、请求参数与鉴权

Query 参数

Header 参数

若未提供 API Key，接口仍可调用，但受每日 30 次体验限制。正式接入建议申请 Key（请参考官方文档获取）。

四、curl 接入示例

以下示例展示了带 API Key 的 GET 请求。将$APIZERO_API_KEY替换为你实际的密钥。

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/bencao?msg=人参"

若不携带 API Key，直接调用：

curl -sS \ -X GET \ "https://v1.apizero.cn/api/bencao?msg=丁香"

返回示例（JSON 格式）：

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

五、代码接入示例

Python 3

使用requests库发起请求，并处理响应。

import requests API_URL = "https://v1.apizero.cn/api/bencao" API_KEY = "your_api_key_here" # 如无密钥留空 params = {"msg": "甘草"} headers = {} if API_KEY: headers["X-API-Key"] = API_KEY try: resp = requests.get(API_URL, params=params, headers=headers, timeout=10) data = resp.json() if data.get("code") == 0: herb = data["data"] print(f"药材: {herb['name']}") print(f"详情:\n{herb['detail']}") else: print(f"请求失败: {data['msg']}") except requests.exceptions.RequestException as e: print(f"网络错误: {e}")

JavaScript (Node.js)

使用axios或原生fetch。以下为 fetch 示例：

const API_URL = 'https://v1.apizero.cn/api/bencao'; const API_KEY = 'your_api_key_here'; // 可选 async function queryHerb(name) { const params = new URLSearchParams({ msg: name }); const headers = {}; if (API_KEY) headers['X-API-Key'] = API_KEY; try { const res = await fetch(`${API_URL}?${params}`, { headers }); const json = await res.json(); if (json.code === 0) { console.log(`药材: ${json.data.name}`); console.log(json.data.detail); } else { console.error(`错误: ${json.msg}`); } } catch (err) { console.error('请求异常:', err); } } queryHerb('当归');

六、返回字段详解

成功响应（HTTP 200）JSON 结构如下：

其中data.detail字符串通常包含多行，以\n分隔，内容为释名、气味、主治等章节。开发者可直接显示或按需解析。

错误响应

• 4040 状态码：未找到精确匹配，响应体含有suggestions数组。示例：

  { "code": 4040, "data": { "suggestions": ["人参", "枸杞"] }, "msg": "未找到匹配项，以下为相关建议", "request_id": "abc123" }

• 400 参数错误：msg为空或超长。
• 401 鉴权失败：API Key 无效或超出调用次数限制。

七、常见错误排查

1. 返回 4040 而非 200：请检查药材名称是否准确，或利用suggestions提示正确名称。
2. HTTP 401：确认 API Key 是否正确，或当日接口调用已达上限。
3. 请求超时：网络环境不稳定，建议设置合理的超时时间（如 10 秒）。
4. 返回乱码：确保请求头Accept为application/json，并正确解码 UTF-8。

八、工程化注意事项

• 缓存策略：中药材数据几乎不变，可对相同msg的响应缓存较长时间（如 24 小时），减少重复调用。
• 并发控制：QPS 10/s，建议在客户端实现请求队列或限流，避免触发限频。
• 错误重试：对 5xx 错误可进行指数退避重试（最多 3 次），对 4xx 错误则需修正请求。
• 数据解析：detail字段的换行符\n在不同平台需正确处理（如网页渲染为<br>）。
• 医疗合规：前端展示应明确标注“数据仅供学习参考，不构成医疗建议”。

九、参考文档

• 官方文档页：https://apizero.cn/aidocs/bencao
• 原始文档（Markdown）：https://apizero.cn/aidocs/bencao/raw.md