健康知识 API 返回字段全解：分类列表 / 搜索结果 / 知识详情三大结构
# 健康知识 API 返回字段全解：分类列表 / 搜索结果 / 知识详情三大结构
- **接口/接入点**：健康知识 · 分类列表 `90-86` / 搜索知识 `90-87` / 查看单条详情 `90-88`（免费）
- **请求方式**：POST / GET ｜ **返回格式**：JSON
- **适用人群**：所有接入该接口的开发者（字段速查） ｜ **阅读时间**：约 7 分钟
## 核心要点
- 三个接入点共用同一套**系统级包裹**（`showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_fee_num`），业务数据都在 `showapi_res_body` 内。
- 三个接入点的业务返回结构各不相同：`list`（分类）、`pagebean.contentlist`（搜索结果）、`item`（详情）。
- 本文是字段速查页，建议收藏，其他文章均链回此处。
## Why：为什么需要一份字段速查
健康知识 API 有三个接入点，返回结构差异较大：分类是扁平数组，搜索是带分页的 `pagebean`，详情是单条 `item`。写代码时若每次都翻官方文档很慢，也容易漏字段。本文把三套结构并列成表，作为全系列的统一速查页。
## What：统一包裹与三类业务结构
所有接入点最外层均为 ShowAPI 统一包裹：
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | int | 系统级状态码，0 为成功 |
| `showapi_res_error` | string | 系统级错误信息 |
| `showapi_res_id` | string | 本次请求唯一标识 |
| `showapi_fee_num` | int | 本次调用计费次数 |
| `showapi_res_body` | object | 业务数据容器 |
`showapi_res_body` 内三个接入点的差异如下。
### 1) 分类列表 `90-86` → `showapi_res_body`
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | string | 业务状态，"0" 成功 |
| `list` | array | 分类数组 |
| `list[].id` | number | 分类 id |
| `list[].name` | string | 分类名称 |
### 2) 搜索知识 `90-87` → `showapi_res_body`
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | string | 成功标志，"0" 为成功，其它失败 |
| `remark` | string | 调用描述 |
| `pagebean` | object | 分页容器 |
| `pagebean.allPages` | number | 总页数 |
| `pagebean.currentPage` | number | 当前页 |
| `pagebean.allNum` | number | 总条数 |
| `pagebean.maxResult` | number | 每页最大数（文档标明每页最大返回 20 条） |
| `pagebean.contentlist` | array | 知识列表 |
| `contentlist[].id` | string | 知识文章 id |
| `contentlist[].title` | string | 标题 |
| `contentlist[].keywords` | string | 关键词 |
| `contentlist[].tname` | string | 分类名称 |
| `contentlist[].media_name` | string | 媒体人 |
| `contentlist[].tid` | string | 分类 id |
| `contentlist[].wapurl` | string | 知识文章原链接地址 |
| `contentlist[].ctime` | string | 发布时间 |
| `contentlist[].intro` | string | 简介 |
| `contentlist[].url` | string | 知识文章原链接地址 |
### 3) 查看单条详情 `90-88` → `showapi_res_body`
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | string | 业务状态 |
| `remark` | string | 调用描述 |
| `item` | object | 单条知识详情 |
| `item.id` | string | 知识文章 id |
| `item.content` | string | 知识文章内容（长文） |
| `item.title` | string | 标题 |
| `item.keywords` | string | 关键词 |
| `item.stitle` | string | 副标题 |
| `item.img` | string | 图片（文档标注"图片（无）"，实际通常为空） |
| `item.tname` | string | 分类名称 |
| `item.media_name` | string | 媒体人 |
| `item.tid` | string | 分类 |
| `item.ctime` | string | 发布时间 |
| `item.intro` | string | 简介 |
## How：用字段表校验你的解析代码
解析时建议先判断系统级 `showapi_res_code === 0`，再判断业务级 `showapi_res_body.ret_code === "0"`，最后按接入点取对应字段：
```python
def parse(body):
# body = data["showapi_res_body"]
if body.get("ret_code") != "0":
raise ValueError(f"业务错误: {body.get('ret_code')}")
# 按接入点取数
if "list" in body: # 分类列表
return body["list"]
if "pagebean" in body: # 搜索知识
return body["pagebean"]["contentlist"]
if "item" in body: # 查看单条
return body["item"]
```
## 返回示例与解析
分类列表示例（结构示意，实际内容以接口返回为准）：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"list": [
{ "id": 103, "name": "综合资讯" },
{ "id": 101, "name": "疾病科普" }
],
"ret_code": "0"
}
}
```
搜索结果 `pagebean` 示例（结构示意）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "",
"pagebean": {
"allPages": 3,
"currentPage": 1,
"allNum": 45,
"maxResult": 20,
"contentlist": [
{ "id": "123", "title": "感冒了怎么办", "tname": "疾病科普", "ctime": "2024-01-15 10:00:00", "intro": "感冒常见症状与应对。" }
]
}
}
}
```
## 进阶 / 边界
- `ret_code` 在官方 schema 中为 string，但官方返回示例中也以数字 `0` 出现；解析时建议用宽松比较（字符串 `"0"` 或数字 `0` 都算成功）。
- `img` 字段文档明确标注"图片（无）"，前端务必做无图兜底（见[内容渲染避坑](https://www.showapi.com/guides/health-knowledge-render-90)）。
- `ctime` 字段文档未规定具体时间格式，以接口实际返回字符串为准，展示时建议先按字符串原样显示。
## FAQ
**Q：三个接入点的返回字段能混用吗？**
A：不能。分类用 `list`、搜索用 `pagebean.contentlist`、详情用 `item`，字段集合不同，请按接入点分别解析。
**Q：ret_code 是字符串还是数字？**
A：schema 定义为 string（"0"），但官方示例中也见到数字 0；兼容两者最稳妥。
**Q：showapi_fee_num 在免费接口里是什么？**
A：计费次数；免费接口下通常为 0 或体现免费档位消耗，具体以实际返回为准。
**Q：搜索结果里 wapurl 和 url 有什么区别？**
A：文档中两者均标注为"知识文章原链接地址"，可任选其一作为原文跳转；实际以接口返回字段为准。
## 相关能力与下一步阅读
- [健康知识 API：5 分钟接入，获取每日健康养生内容](https://www.showapi.com/guides/health-knowledge-quickstart-90)
- [健康知识 API：搜索知识接入实战（关键词 / 分类 / 分页）](https://www.showapi.com/guides/health-knowledge-search-90)
- [健康知识 API：查看单条知识详情与长文渲染](https://www.showapi.com/guides/health-knowledge-detail-90)
- **本系列共 12 篇**：查看[健康知识 API 使用指南总目录](https://www.showapi.com/guides/health-knowledge-guides-90)
