图书ISBN查询避坑指南：字段缺失、更新频率与免费档位限制
# 图书ISBN查询避坑指南：字段缺失、更新频率与免费档位限制
> 接口/接入点：图书ISBN查询（1626-1） · 是否免费：免费（有使用档次限制） · 请求方式：POST / GET · 返回格式：JSON · 适用人群：已接入用户 · 阅读时间：约 6 分钟
## TL;DR
- 部分字段（如 `produce`、`paper`）可能为空，展示端务必空值兜底，不要写死。
- 更新频率"每天不定时更新多次，本月出版物一般当月可查"——极新书可能稍晚入库。
- 免费但有档次限制，高频场景务必加缓存省额度；`data` 是对象不是数组。
## Why
接入后最容易踩的坑就三类：把空字段当必然存在、对更新时效预期错误、忽视免费档位被限流。本文把实测中常见的坑一次性讲清，照着做能少走很多弯路、少接工单。
## What
| 坑 | 现象 | 正确做法 |
|----|------|---------|
| 字段缺失 | `produce`/`paper` 为空 | 展示"—"或占位，支持人工补录 |
| 更新时效 | 刚出版的新书查不到 | 隔日重试；不视为接口故障 |
| 免费档位 | 量大被限流 | 加缓存、控并发（见缓存策略篇） |
| `data` 类型 | 当数组遍历取不到 | `data` 是单个对象，直接取字段 |
| 两级返回码 | 只判一层 | 系统级 `showapi_res_code` 与业务级 `ret_code` 都判 |
## How
### 步骤 1：空值安全取值
```python
def safe_get(d: dict, key: str, default="-") -> str:
v = d.get(key)
return v if v not in (None, "") else default
title = safe_get(book, "title")
produce = safe_get(book, "produce") # 可能为空
```
### 步骤 2：更新时效的容错
```python
book = lookup_book(isbn)
if not book:
# 极新书可能尚未入库：记录待重试，次日再查一次
schedule_retry(isbn, delay_days=1)
```
### 步骤 3：档位保护
- 以 `isbn` 为 key 缓存（命中即不调接口）。
- 客户端限流（如令牌桶），避免突发打满免费档位。
- 监控剩余额度，临近上限时优先保障核心查询。
## 返回示例与解析
正常返回 `data` 为单对象；空字段在 JSON 里可能是空字符串，解析时用 `safe_get` 兜底。
## 进阶 / 边界
- **`produce` 语义未定义**：文档未给出确切含义，示例多为日期；当作可选信息，不依赖它做关键逻辑。
- **不要编造字段**：返回字段以文档"返回参数"为准，不要在展示里引用不存在的字段（如"畅销热度"）。
- **重试要区分**：仅系统/网络错误重试；业务"未找到"不重试（号未变结果不变）。
## FAQ
**Q1：为什么有的书没有装帧/纸张信息？**
部分图书元数据本身缺失，属正常；展示端空值兜底即可，不影响其他字段。
**Q2：今天刚出的书查不到，是接口坏了吗？**
大概率尚未入库。文档说明"本月出版物一般当月可查"，极新书可隔日重试。
**Q3：免费档位被限流了怎么办？**
加缓存降低真实调用量、做客户端限流；具体档位以官方档位说明页为准。
**Q4：data 用数组还是对象？**
单对象。文档文字曾标 `Object[]`，但真实返回为单个对象，按对象解析。
## 相关能力 / 下一步阅读
- [图书ISBN查询免费档位下如何设计缓存策略省调用额度](https://www.showapi.com/guides/isbn-book-cache-cost-1626)
- [图书ISBN查询错误码排查：ret_code 非 0 与"查不到"怎么办](https://www.showapi.com/guides/isbn-book-error-handling-1626)
- [图书ISBN查询返回字段全解：一本书的 13 个元数据字段一文读懂](https://www.showapi.com/guides/isbn-book-fields-explained-1626)
- **本系列共 12 篇**：查看[图书ISBN查询（apiCode=1626）官方指南总目录](https://www.showapi.com/guides/isbn-book-guides-1626)
