中文近义词反义词 API：返回结构全解（ret_code 与 result 数组）
中文近义词API中文反义词API免费接口ShowAPI # 中文近义词反义词 API：返回结构全解（ret_code 与 result 数组）
> 接口：免费近义词 - 中文近义词和反义词（apiCode=1624）· 免费服务 · POST/GET · 返回 JSON · 适用人群：初级~中级开发者 · 阅读时间：约 6 分钟
## 核心要点
- 返回分两层：系统级（`showapi_res_code` 等）和业务级（`showapi_res_body` 内的 `ret_code` / `result`）。
- **`result` 是数组**，不是文档里写的 `String`；每个元素是 `{words, wordsDetail}`。
- 成功判定要两层都为 0：系统级 `showapi_res_code==0` 且业务级 `ret_code==0`。
## Why：为什么要把返回结构搞清楚
很多调用失败不是接口坏了，而是没分清"系统级成功"和"业务成功"，或者按文档把 `result` 当字符串处理导致报错。本文把实测返回的每一层字段讲清楚，让你写解析代码时一次写对。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 请求地址 | `https://route.showapi.com/1624-1`（近义）/ `1624-2`（反义） |
| 必填参数 | `keyWords`（String） |
| 鉴权 | `appKey` 查询参数 |
| 返回格式 | JSON |
| 成功判定 | `showapi_res_code==0` 且 `showapi_res_body.ret_code==0` |
## How：逐层解析（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/1624-1",
params={"appKey": APP_KEY},
data={"keyWords": "残酷"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
data = resp.json()
# 第一层：系统级
if data.get("showapi_res_code") != 0:
# 网络/鉴权/路由层问题，看 showapi_res_error
raise RuntimeError(data.get("showapi_res_error"))
# 第二层：业务级
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
# 业务失败，看 remark
raise RuntimeError(body.get("remark"))
# result 是数组，逐条处理
for item in body["result"]:
word = item["words"] # 词名
detail = item["wordsDetail"] # 拼音 + 词性 + 释义
print(word, detail)
```
## 返回示例与解析（真实返回，已精简）
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "6a990ad9fb638c8138888397",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"result": [
{"words": "严酷", "wordsDetail": "[ yán kù ] （形）①严厉；严格：～的教训。②残酷；冷酷：～的剥削。"},
{"words": "冷酷", "wordsDetail": "[ lěng kù ] （形）对待别人冷漠残酷：～无情|手段～。"}
]
}
}
```
### 系统级字段（`showapi_res_body` 之外）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | int | 系统级状态码，0 成功 |
| `showapi_res_error` | String | 系统级错误信息，成功时为空 |
| `showapi_res_id` | String | 本次请求追踪 ID |
| `showapi_fee_num` | int | 本次消耗计量（免费接口实测=1） |
### 业务级字段（`showapi_res_body` 内）
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | int/String | 业务状态码，0 成功，非 0 失败 |
| `result` | **Array** | 近义/反义词数组，每个元素 `{words, wordsDetail}` |
| `remark` | String | 业务说明，失败时承载失败原因 |
### `result` 数组元素字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `words` | String | 近义/反义词名 |
| `wordsDetail` | String | 拼音 + 词性 + 释义（如 `[ yán kù ] （形）①严厉；严格…`） |
> ⚠️ **文档偏差修正**：接口文档的"返回体"一节把 `result` 标为 `String`、并把 `words`/`wordsDetail` 列为 body 平级字段。实测 `result` 是**数组**，`words`/`wordsDetail` 在数组元素内。按文档写会解析失败，请以上表为准。
## 进阶 / 边界
- 空结果：`result` 为 `[]`（该词无近义/反义词），不是错误，按"无结果"分支处理。
- 多义项：`wordsDetail` 内可能含"①…②…"分项，按需要自行拆分展示。
- 失败分支：文档未提供 `ret_code` 的具体非零枚举值，统一以"非 0 即失败、看 `remark`"处理，不要硬编码具体错误码。
## FAQ
**Q1：为什么我按文档把 result 当成字符串取字段会报错？**
A：文档把 `result` 标成了 `String`，但实测它是数组。正确做法是遍历 `result` 数组，取每个元素的 `words`/`wordsDetail`。
**Q2：ret_code 和 showapi_res_code 都要判断吗？**
A：建议都判断。前者是业务层（词查询是否成功），后者是系统/鉴权层。两层都为 0 才是真正成功。
**Q3：showapi_fee_num 是什么？**
A：本次调用消耗的计量数。免费接口每次=1，从免费额度扣除；它不是错误字段。
**Q4：失败时错误码有哪些？**
A：文档未给出 `ret_code` 的非零枚举值。统一按"非 0 即失败"处理，原因读 `remark` 字段即可。
**Q5：result 为空数组算成功吗？**
A：算。`ret_code==0` 且 `result==[]` 表示该词没有关联的近义/反义词，属正常业务结果。
## 相关能力 / 下一步阅读
- [中文近义词反义词 API：5 分钟接入，从注册到第一条查询结果](https://www.showapi.com/guides/chinese-synonym-antonym-quickstart-1624)
- [中文近义词反义词 API：近义词与反义词双接入点详解](https://www.showapi.com/guides/chinese-synonym-antonym-access-points-1624)
- **本系列共 8 篇**：查看[中文近义词反义词 API 使用指南总目录](https://www.showapi.com/guides/chinese-synonym-antonym-guides-1624)
