常见疾病查询返回字段全解：科目树、疾病列表与明细结构一文读懂
# 常见疾病查询返回字段全解：科目树、疾病列表与明细结构一文读懂
> 接口：常见疾病查询（apiCode=546）· 免费 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：开发者、需对接返回结构的工程师 · 阅读时间：约 6 分钟
## 核心要点
- 三个接入点的返回**结构层级不同**：546-1 是「科目树」，546-2 是「疾病列表」，546-3 是「疾病明细」。
- 关键区分：**只有 546-3 的明细带 `tagList`（症状/诊断/治疗/预防）和 `alias`**；546-2 列表项没有这两项。
- 成功判定统一用 `ret_code == 0`（文档仅定义 0=成功、非0=失败，**无细分错误码表**）；系统级看 `showapi_res_code`。
## Why：为什么要先搞懂返回结构
对接任何接口，最先踩的坑往往不是"怎么调"，而是"返回里哪个字段才是我要的"。常见疾病查询的三个接入点返回长得不像：
- 你想做导诊推荐，要的是 `typeId`/`typeName`（科室），来自 546-1 和 546-2。
- 你想展示"这个病有什么症状、怎么治"，要的是 546-3 的 `tagList`——**但 546-2 的列表里没有它**，必须再用 `id` 调一次 546-3。
本文把三套结构一次讲清，避免你拿列表当明细、漏掉 `tagList`。
## What：接口速览
| 接入点 | 用途 | 必填参数 | 核心返回 |
|--------|------|---------|---------|
| 546-1 查询疾病科目 | 科室分类树 | 无 | `list[]`：{typeName, typeId, subList[{subName, subId}]} |
| 546-2 关键字查询疾病 | 疾病列表 | 无（id 在 546-3 才必填） | `contentlist[]`：{id, name, summary, typeName, typeId, subTypeId, subTypeName} |
| 546-3 取得疾病明细 | 疾病详情 | `id`（来自 546-2） | `item[]`：{id, name, summary, alias, typeName, typeId, subTypeId, subTypeName, tagList[{name, content}]} |
返回包裹（三接入点一致）：`showapi_res_code`（系统级）、`showapi_res_error`、`showapi_res_id`、`showapi_res_body`（业务数据）。
## How：三套结构对照
### 546-1 科目树
```json
{
"showapi_res_body": {
"ret_code": 0,
"list": [
{
"typeName": "内科",
"typeId": "3",
"subList": [
{ "subName": "呼吸内科", "subId": "0301" },
{ "subName": "消化内科", "subId": "0302" }
]
}
]
}
}
```
### 546-2 疾病列表（注意：无 tagList / alias）
```json
{
"showapi_res_body": {
"ret_code": 0,
"contentlist": [
{
"id": "xxxxx",
"name": "高血压",
"summary": "以体循环动脉血压增高为主要表现...",
"typeName": "内科",
"typeId": "3",
"subTypeId": "0304",
"subTypeName": "心血管内科"
}
]
}
}
```
### 546-3 疾病明细（含 tagList / alias）
```json
{
"showapi_res_body": {
"ret_code": 0,
"item": [
{
"id": "xxxxx",
"name": "高血压",
"summary": "以体循环动脉血压增高为主要表现...",
"alias": "高血压病",
"typeName": "内科",
"typeId": "3",
"subTypeId": "0304",
"subTypeName": "心血管内科",
"tagList": [
{ "name": "症状", "content": "头晕、头痛、颈项板紧..." },
{ "name": "诊断", "content": "基于诊室/动态/家庭血压测量..." },
{ "name": "治疗", "content": "生活方式干预+降压药物..." },
{ "name": "预防", "content": "减盐、控制体重、规律运动..." }
]
}
]
}
}
```
### Python：安全取值
```python
def first_item(body, key):
arr = body.get(key) or []
return arr[0] if arr else None
# 取明细的"症状"标签
detail = call("546-3", id=disease_id)
it = first_item(detail, "item")
if it:
tags = {t["name"]: t["content"] for t in it.get("tagList", [])}
print("症状:", tags.get("症状"))
print("治疗:", tags.get("治疗"))
```
### cURL
```bash
curl -X POST "https://route.showapi.com/546-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "id=<疾病id>"
```
### Node.js（fetch）
```javascript
const detail = await call("546-3", { id: diseaseId });
const it = (detail.item || [])[0];
const tags = Object.fromEntries((it?.tagList || []).map(t => [t.name, t.content]));
console.log("症状:", tags["症状"]);
```
## 返回示例与解析（字段表）
| 字段 | 类型 | 出现于 | 说明 |
|------|------|--------|------|
| `showapi_res_code` | int | 全部 | 系统级状态码，0=成功 |
| `showapi_res_body.ret_code` | number/string | 全部 | 业务级，0=成功；非0失败（无细分码） |
| `list[].typeName` / `typeId` | string | 546-1 | 一级科目名称/编号 |
| `list[].subList[].subName` / `subId` | string | 546-1 | 二级子科目名称/编号 |
| `contentlist[].id` / `name` | string | 546-2 | 疾病 id（供 546-3 用）/ 名称 |
| `contentlist[].typeId`/`subTypeId` | string | 546-2 | 所属一/二级科室 |
| `item[].alias` | string | 546-3 | 疾病别名 |
| `item[].tagList[].name`/`content` | string | 546-3 | 标签名（症状/诊断/治疗/预防等）/内容 |
## 进阶 / 边界
- **`ret_code` 类型不一致**：546-1 文档定义为 number，546-2/546-3 描述为 string，但值都是 `0`。代码里统一用 `str(ret_code) == "0"` 判定，避免类型坑。
- **`tagList` 只在明细**：列表接口 546-2 不返回 `tagList`，别在列表页就去找症状。
- **无细分错误码**：文档只给了「0=成功，其他失败」，没有 -2/-3 之类的枚举。排查失败时读 `showapi_res_error` 或业务返回信息。
## FAQ
**Q1：为什么我在 546-2 的返回里找不到症状？**
A：症状/诊断/治疗/预防在 546-3 的 `tagList` 里，不在 546-2 列表。先用 546-2 拿到 `id`，再调 546-3。
**Q2：ret_code 返回 "0" 字符串算成功吗？**
A：算。判定统一用「等于 0」，建议用字符串比较 `str(ret_code) == "0"` 兼容 number/string。
**Q3：subId 和 typeId 是什么关系？**
A：`typeId` 是一级科室编号（如内科=3），`subId` 是其下二级子科目编号（如心血管内科=0304），两者父子关系。
**Q4：文档有错误码明细吗？**
A：没有。官方仅定义 `ret_code` 0=成功、非0=失败，无细分表；失败时看 `showapi_res_error`。
## 相关能力 / 下一步阅读
- [常见疾病查询：取得疾病明细并解析症状/诊断/治疗/预防（546-3 的 tagList）](https://www.showapi.com/guides/disease-query-detail-546)
- [常见疾病查询：关键字检索疾病（546-2 的 typeId/subTypeId/key/page 用法）](https://www.showapi.com/guides/disease-query-keyword-search-546)
- [常见疾病查询：5 分钟从注册到拿到第一篇疾病明细](https://www.showapi.com/guides/disease-query-quickstart-546)
- **本系列共 12 篇**：查看[常见疾病查询指南总目录](https://www.showapi.com/guides/disease-query-guides-546)
