企业官网建设流程全解析

从一个实际需求说起

在做中医养生类小程序时，经常需要在用户输入药材名称后展示对应的释名、气味、主治与附方。这类功能并不适合自己爬取古籍数据，原因有三：数据清洗维护复杂度高、文本结构不统一、维护周期长。相比之下，直接调用一个现成的中药材知识接口，把精力放在前端交互与业务逻辑上，是更务实的路径。

本草纲目·中药查询（slug:bencao）正是这样一个面向传统中药材知识检索的 HTTP GET 接口。它接收中文药材名称，返回《本草纲目》中对应的释名、气味、主治与附方等文本记载。本文不讨论接口之外的平台能力，只聚焦这个接口本身：它擅长什么、边界在哪里、请求怎么写、返回怎么读、错误怎么处理。

适用场景：哪些业务适合接入

这个接口适合作为“知识展示型”功能的数据源，典型场景集中在以下几个方向：

1. 中医养生 / 食疗 App 的药材百科：用户搜索“枸杞”或“甘草”，页面展示该药材的释名、性味与主治。接口返回的detail字段本身是按《本草纲目》体例组织好的文本，适合直接渲染。
2. 中药知识科普类小程序：内容型产品需要稳定的药材解释文本，接口的name与matched字段可以辅助前端判断是否命中精确词条。
3. AI 中医问诊辅助参考：作为大模型生成回答前的知识检索补充，注意接口数据仅作参考，不能作为唯一诊疗依据。
4. 古籍数字化项目：需要将《本草纲目》部分条目录入系统时，可通过接口做批量拉取与文本校对，但需要注意 QPS 限制。
5. 国学 / 中医文化教学：在课件或互动页面中嵌入药材查询，帮助学生快速获取原文描述。

从接口设计来看，msg参数只接受中文药材名，因此它更适合“已知名称查详情”的场景，而不是“按拼音首字母查列表”或“按功效反查药材”这类检索需求。

接口能力边界：能做什么，不能做什么

数据覆盖范围

接口数据整理自《本草纲目》及网络公开整理资料，覆盖常见中药材。以人参、丁香、甘草、枸杞为代表的常用药材可以直接命中。对于冷门药材或地方别名，接口不一定能返回exact匹配，此时会进入模糊建议逻辑。

匹配逻辑：exact 与 suggestions 的分工

这是整个接口最核心的行为边界，直接影响客户端交互设计。

• 当msg传“人参”，且词条精确存在时，返回matched: "exact"，data中直接携带name与detail。
• 当msg传“人参枸杞”这类复合词或一个不存在的药名时，接口不会返回 404 或空数组，而是返回业务码 4040，并在响应中附带suggestions数组，最多 10 个相关建议。

例如查询“人参枸杞”，suggestions中可能出现“人参”“枸杞”等单味药名称。这意味着接口对输入容错不做强制约束，而是把纠错责任交给调用方。

响应的文本结构

detail字段是自由文本，内部用「释名」「气味」「主治」等小标题分行组织，字段内以换行符分隔。这不是结构化 JSON 字段，因此无法直接通过data.detail.主治这样的路径取值。如果业务上需要按条目区分展示，调用方需要自己做文本解析。

接口定位与限制

• 请求方法：GET
• 请求地址：https://v1.apizero.cn/api/bencao
• QPS：10 / s

QPS 为 10 意味着单实例下游并发循环调用时，每秒最多处理 10 个请求。超过后可能触发限流，需要在客户端加节流或排队。

参数与鉴权

Query 参数

msg是唯一必填参数。注意：接口不承诺对英文名或拼音的兼容，传“renshen”大概率进入建议流程而非精确匹配。

Header 鉴权

未携带鉴权信息时，存在每日体验次数限制（素材标注为 30 次/天）。接入生产环境时建议申请 API Key，并在服务端保存，避免把 Key 暴露在 Web 端代码中。

curl 接入示例

以下示例直接调用接口查询“人参”：

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

如果暂时没有 API Key，也可以不携带X-API-Key头直接请求体验：

curl -sS "https://v1.apizero.cn/api/bencao?msg=甘草"

建议将$APIZERO_API_KEY配置为环境变量，而不是硬编码在代码仓库中。

返回字段解读

成功时 HTTP 状态码为 200，响应体是一个 JSON 数组，数组内单个元素结构如下：

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

关键字段说明：

注意example字段包裹在数组元素中，解析时先取数组第一个元素，再读example，最后取data。实际响应结构需要以接口在线返回为准，建议接入后先打印一次完整响应体再做结构绑定。

常见错误与处理策略

场景一：找不到药材，返回 4040

当msg无法精确匹配时，响应中的code变为非 0（典型为 4040），同时响应中携带suggestions数组。此时前端不应把data.detail渲染为“空”，而是展示“未找到该药材”并列出建议名称。

{ "code": 4040, "msg": "未找到精确匹配，请参考建议", "data": { "suggestions": ["人参", "枸杞"] } }

场景二：参数缺失或为空

msg为必填参数。调用时未传msg或传入空字符串，通常会得到参数校验错误。调用方应在客户端先做非空校验，避免无效请求占用 QPS。

场景三：鉴权失败

携带了错误的 API Key 时，接口会返回鉴权相关错误。建议排查：

• 环境变量是否真实注入
• Header 名称是否与申请时约定的一致（Authorization或X-API-Key）
• Key 是否包含多余空格或换行

场景四：QPS 超限

单实例 QPS 限制为 10。若业务需要批量查询多个药材，建议在客户端引入队列或定时器，将请求速率控制在安全阈值内。另外，对同一药材的重复查询应做本地缓存，减少不必要的上游调用。

工程化注意事项

1. 做好 detail 文本的展示适配

detail是换行分隔的纯文本，字段内使用「释名」「气味」「主治」作为小节标题。在移动端展示时，建议按换行符分割后逐行渲染，并对小节标题加粗或变色，提升阅读体验。

2. 建立名称归一化映射

同一药材可能有多个别名。接口虽然能返回“人参”的精确词条，但用户输入“神草”时不一定能直接命中。建议业务侧维护一份常用别名到标准名的映射表，先做本地归一化，再调用接口。

3. 合理使用 suggestions

suggestions是接口给出的纠错信号。可以在 UI 上以标签形式展示，用户点击后自动替换msg重新请求。不要在用户无感知的情况下自动请求第一个建议，避免展示错误的药材详情。

4. 关于数据合规使用

接口文档明确说明：数据整理自《本草纲目》及网络公开整理资料，仅供学习参考；中医药疗用请遵医嘱。这意味着：

• 不适合在医疗诊断场景中作为唯一判断依据
• 在医疗健康类应用中展示时，应附带“仅供参考”的免责声明
• 若涉及二次分发，需自行评估内容版权与合规要求

5. 缓存与降级

常用药材的详情文本变化频率极低，适合做本地缓存，例如以name为 key、detail为 value，缓存周期可设置为天级。当接口限流或网络异常时，可以回退到缓存数据，保证页面不白屏。

6. 监控请求_id

每次响应都包含request_id，建议在日志中记录该字段。排查调用链问题时，这个 id 是定位服务端日志的关键线索。

总结

本草纲目·中药查询接口的价值在于：用最简参数获取结构化的古籍药材知识文本，适合快速搭建药材百科类功能。它的边界同样明显：只接受中文名称查询、QPS 为 10、detail为自由文本、冷门药材依赖模糊建议。开发者在接入前应评估自身业务是否需要高频查询、是否需要结构化字段、是否接受“建议式纠错”的交互形态。把接口的边界融入到产品设计中，才能避免上线后的返工。

参考文档

• 文档页：https://apizero.cn/aidocs/bencao
• 原始文档：https://apizero.cn/aidocs/bencao/raw.md