中文分词接口返回字段全解：list 分词数组与 ret_code 一文读懂
chinese-segmentation-response-fields-269 # 中文分词接口返回字段全解：list 分词数组与 ret_code 一文读懂
> 接口：中文分词接口（269-1） · 免费 · POST/GET · JSON · 适用人群：初级~中级开发者 · 阅读时间：6 分钟
## 核心要点
- 业务数据统一包在 `showapi_res_body` 内，本接口只暴露两个字段：`list`（分词数组）和 `ret_code`（0 成功）。
- 系统级字段 `showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_fee_num` 由网关统一返回，与具体业务无关。
- 重点提醒：返回结构**只有分词数组**，没有词性/实体字段，解析时按字符串数组处理即可。
## Why：读懂返回才能写对代码
很多调用失败或解析报错，根源是没搞清楚"哪些字段是网关包的、哪些是业务自己的"。本文把返回结构拆开讲清楚，让你写解析逻辑时心里有数，也避免去解析根本不存在的字段。
## What：返回结构速览
| 字段 | 层级 | 类型 | 含义 |
|------|------|------|------|
| `showapi_res_code` | 系统级 | Integer | 网关层状态码，`0` 成功 |
| `showapi_res_error` | 系统级 | String | 网关层错误信息，成功时为空 |
| `showapi_res_id` | 系统级 | String | 本次请求唯一标识，便于排查 |
| `showapi_fee_num` | 系统级 | Integer | 本次计费计数 |
| `showapi_res_body` | 业务包裹 | Object | 业务数据均在此对象内 |
| `showapi_res_body.ret_code` | 业务级 | String | `0` 为成功，其他为失败 |
| `showapi_res_body.list` | 业务级 | String 数组 | 切词结果，每个元素是一个词 |
## How：解析示例
**Python**
```python
import urllib.request, urllib.parse, json
APP_KEY = "YOUR_APPKEY"
url = f"https://route.showapi.com/269-1?appKey={APP_KEY}"
data = urllib.parse.urlencode({"text": "易源接口是api的可插拔总线"}).encode("utf-8")
req = urllib.request.Request(url, data=data,
headers={"content-type": "application/x-www-form-urlencoded"})
with urllib.request.urlopen(req, timeout=10) as resp:
result = json.loads(resp.read().decode("utf-8"))
# 1) 先判断网关层
if result.get("showapi_res_code") != 0:
print("网关错误：", result.get("showapi_res_error"))
else:
body = result.get("showapi_res_body", {})
# 2) 再判断业务层
if body.get("ret_code") == 0:
words = body.get("list", []) # 分词数组：["易源","接口","api","插拔","总线"]
print("词数：", len(words))
print("分词：", " / ".join(words))
else:
print("业务失败 ret_code=", body.get("ret_code"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/269-1?appKey=YOUR_APPKEY" \
--data-urlencode "text=易源接口是api的可插拔总线"
```
**Node.js**
```js
const url = `https://route.showapi.com/269-1?appKey=YOUR_APPKEY`;
fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ text: "易源接口是api的可插拔总线" }).toString()
})
.then(r => r.json())
.then(res => {
if (res.showapi_res_code !== 0) return console.log("网关错误", res.showapi_res_error);
const b = res.showapi_res_body || {};
if (b.ret_code === 0) console.log("分词：", b.list.join(" / "));
else console.log("业务失败", b.ret_code);
})
.catch(e => console.error(e));
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "6a9648e5fb638c3463281397",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"list": ["易源", "接口", "api", "插拔", "总线"]
}
}
```
`list` 是**纯字符串数组**，每个元素就是一个词；数组顺序即原文中的出现顺序。
## 进阶 / 边界
- `ret_code` 在文档中仅标注「0 为成功，其他失败」，未给出完整的非 0 枚举值；代码里用 `!= 0` 判失败即可，不要去匹配不存在的具体错误码。
- 不要假设 `list` 里有 `pos`（词性）或 `entity`（实体）这类子字段——当前返回结构没有，强行读取会得到 `undefined`。
## FAQ
**Q：list 里的元素顺序有保证吗？**
A：有，按原文词序排列，可直接用于还原句子结构或做顺序相关的处理。
**Q：ret_code 和 showapi_res_code 有什么区别？**
A：`showapi_res_code` 是网关/调用层（鉴权、网络、计费），`ret_code` 是业务层（分词本身是否成功）。两层都要判，先网关后业务。
**Q：为什么没有词性标注字段？**
A：本接口返回结构只暴露 `list` 分词数组 + `ret_code`，词性/实体不在返回字段中。详见[常见问题与避坑指南](https://www.showapi.com/guides/chinese-segmentation-faq-269)。
**Q：showapi_fee_num 是什么？**
A：本次调用的计费计数，免费接口也会返回（免费档位内不计费或计为免费额度消耗）。
## 相关能力 / 下一步阅读
- [中文分词接口：5 分钟从注册到拿到第一条分词结果](https://www.showapi.com/guides/chinese-segmentation-quickstart-269)
- [中文分词接口：如何用分词结果做关键词提取与文本标签](https://www.showapi.com/guides/chinese-segmentation-keyword-extraction-269)
- [中文分词接口：常见问题与避坑指南（粒度/繁体/词性标注）](https://www.showapi.com/guides/chinese-segmentation-faq-269)
- **本系列共 11 篇**：查看[中文分词接口指南总目录](https://www.showapi.com/guides/chinese-segmentation-guides-269)
