免费经典语句 API 标签筛选：tag 参数怎么用才不出空结果？
# 免费经典语句 API 标签筛选：tag 参数怎么用才不出空结果？
> 元信息：接口 1646-2 · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群 已接入开发者/产品运营 · 阅读时间 5 分钟
## 核心要点
- `tag` 是**可选**参数，文档示例值为「学习」，用于按主题筛选语句。
- 不传 `tag` 接口返回默认语句（成功，`ret_code=0`）；传了 `tag` 则按主题返回。
- 文档**未列出可用标签清单**，不要预设固定枚举；空结果按"主题不匹配/接口无该主题语料"处理，而非当作报错。
## Why：为什么单独讲 tag
很多开发者第一次用 `tag` 会误以为"传了就一定会返回我想要的"，结果拿到不相关语句或以为失败。本文把 `tag` 的真实语义和边界讲清，避免你在对结果做断言时写出脆弱逻辑。
## What：参数速览
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| `tag` | Body（POST）或 Query（GET） | String | 否 | 标签筛选，文档示例「学习」 |
| `appKey` | Query | String | 是 | 鉴权 |
> 注：以上 `tag`/`appKey` 为官方文档列出的参数；其余字段见 [返回字段全解](https://www.showapi.com/guides/classic-quotes-fields-1646)。
## How：正确传 tag
**POST 方式（推荐，表单）**
Python：
```python
import requests
url = "https://route.showapi.com/1646-2"
params = {"appKey": "YOUR_APPKEY"}
data = {"tag": "学习"} # 可选；不传 data 则返回默认语句
try:
resp = requests.post(url, params=params, data=data, timeout=10)
js = resp.json()
except requests.RequestException as e:
print("请求失败：", e)
raise
if js.get("showapi_res_code") == 0:
b = js["showapi_res_body"]
if b.get("ret_code") == 0:
print(f"{b.get('body')} —— {b.get('author')}《{b.get('name')}》")
else:
print("业务失败 ret_code=", b.get("ret_code"))
```
cURL：
```bash
# 传 tag
curl -X POST "https://route.showapi.com/1646-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "tag=%E5%AD%A6%E4%B9%A0"
# 不传 tag（返回默认语句）
curl -X POST "https://route.showapi.com/1646-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
Node.js（fetch）：
```javascript
const url = "https://route.showapi.com/1646-2?appKey=YOUR_APPKEY";
const form = new URLSearchParams();
form.append("tag", "学习");
const resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: form,
});
const js = await resp.json();
if (js.showapi_res_code === 0 && js.showapi_res_body.ret_code === 0) {
const b = js.showapi_res_body;
console.log(`${b.body} —— ${b.author}《${b.name}》`);
}
```
## 返回示例与解析
传 `tag=学习` 时返回：
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"body": "书山有路勤为径，学海无涯苦作舟。",
"author": "韩愈",
"ret_code": 0,
"name": "古今贤文"
}
}
```
无论是否传 `tag`，只要 `ret_code=0` 即视为成功取到一条语句；空结果或异常应看 `ret_code` 与 `showapi_res_error`，而非假设"tag 写错"。
## 进阶 / 边界
- **可用标签未文档化**：官方只给了「学习」作示例，未提供完整标签表。代码中不要写"支持 N 个标签"之类的量化结论。
- **tag 是软筛选**：文档未承诺精确匹配；对主题一致性敏感的场景，建议在客户端做二次校验或缓存。
- **GET 也可传**：`tag` 同样可作为 query 参数（`?appKey=...&tag=学习`），但中文需 URL 编码。
## FAQ
**Q：不传 tag 会报错吗？**
不会。`tag` 为可选，不传返回默认语句，`ret_code` 仍为 0。
**Q：传了一个不存在的 tag 会怎样？**
文档未定义该行为；以接口实际返回为准。`ret_code` 仍为判断成败的唯一依据，不要对未知 tag 预设"必然失败"。
**Q：tag 支持多个值吗？**
文档仅给出单值示例（如「学习」），未说明多值/数组写法；按单值使用，避免自行拼多值导致不可预期结果。
**Q：怎么知道有哪些可用 tag？**
官方未公布清单，建议以接口实际返回观察，或在产品侧维护你用到的主题白名单，不要假设全量枚举。
**Q：tag 和返回主题不一致怎么办？**
tag 为软筛选，文档未承诺完全一致；可结合 [缓存策略](https://www.showapi.com/guides/classic-quotes-cache-1646) 做本地主题库，客户端二次过滤。
## 相关能力 / 下一步阅读
- [5 分钟接入免费经典语句 API](https://www.showapi.com/guides/classic-quotes-quickstart-1646) — 第一次调用
- [免费经典语句 API 返回字段全解](https://www.showapi.com/guides/classic-quotes-fields-1646) — 字段含义
- [免费接口也要省：经典语句客户端缓存策略](https://www.showapi.com/guides/classic-quotes-cache-1646) — 本地主题库
- **本系列共 11 篇**：查看[免费经典语句 API 开发指南总目录](https://www.showapi.com/guides/classic-quotes-guides-1646)
