车型大全分页与条数上限：maxResults≤20 与缓存策略
# 车型大全分页与条数上限：maxResults≤20 与缓存策略
> 接口/接入点：车型大全（apiCode 1467）· 车型详情 1467-3 · 免费 · POST/GET · JSON · 适用人群：中高级开发者、架构师 · 阅读时间：约 7 分钟
## 核心要点
- 车型详情（1467-3）支持分页：`page`（当前页码，默认 1）与 `maxResults`（每页条数，默认 10，**最大只能查 20 条**）。
- 大车系款型常常超过 20 条，必须循环翻页（`page` 递增）才能拉全，否则会漏数据。
- 车型数据每周六 3 点才更新一次，非常适合用 Redis 等做缓存，既提升响应速度又降低免费额度消耗。
## Why
免费接口一般都有调用额度限制。如果你每次用户打开车型页都去实时查一次，额度很快见底，用户也会觉得慢。车型大全的数据更新很慢（每周一次），本质上"读多写少"，是缓存的绝佳场景。本文给出翻页拉全 + 缓存降耗的落地写法。
## What
| 参数 | 说明 | 注意 |
|------|------|------|
| `page` | 当前页码，从 1 开始 | 默认 1 |
| `maxResults` | 单页最大条数 | 默认 10，**最大 20** |
| `modelId` | 子车系 Id，选填 | 可精确某个子车系 |
返回顶层有 `count`（总条数）、`page`、`maxResult`，可据此判断是否还有下一页。
## How
### 翻页拉全某车系全部款型（Python）
```python
import requests, math
APP_KEY = "YOUR_APPKEY"
BASE = "https://route.showapi.com/1467-3"
def fetch_page(brand_id, serie_id, page, size=20):
r = requests.post(BASE, params={"appKey": APP_KEY, "brandId": brand_id,
"serieId": serie_id, "page": page, "maxResults": size}, timeout=10)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("msg", "fail"))
return body
brand_id, serie_id = "61234c1dbe669bf6be251553", "61235b4dbe66d5b348bddef6"
first = fetch_page(brand_id, serie_id, 1, 20)
total = int(first["count"])
pages = math.ceil(total / 20)
all_models = list(first["data"])
for p in range(2, pages + 1):
all_models += fetch_page(brand_id, serie_id, p, 20)["data"]
print(f"共拉取 {len(all_models)} 条款型")
```
### Redis 缓存降额度
```python
import redis, json
cache = redis.Redis(host="localhost", port=6379, db=0)
def get_models(brand_id, serie_id):
key = f"carmodel:{brand_id}:{serie_id}"
cached = cache.get(key)
if cached:
return json.loads(cached)
# 翻页拉全（见上）后写入，过期时间设为 7 天，对齐"每周六更新"
data = pull_all(brand_id, serie_id)
cache.setex(key, 7 * 24 * 3600, json.dumps(data, ensure_ascii=False))
return data
```
## 返回示例与解析
返回顶层 `count` 表示该查询的总款型数；当 `count > maxResults` 时，需要翻页。注意 `maxResult`（单数，实际返回条数）与 `count`（总数）含义不同。
## 进阶/边界
- `maxResults` 硬上限 20，传大于 20 的值会被拒绝或按上限处理，不要假设能一次拉 100 条。
- 缓存 key 建议用 `brand_id + serie_id` 组合；过期时间设为 7 天（对齐每周六更新），或监听更新窗口在周六 3 点后主动刷新。
- 初始建库时批量翻页落本地库，运行时优先读缓存/本地，避免高频实时查询触发档位限制。
## FAQ
**Q: maxResults 能传 50 吗？**
不能。文档明确"最大只能查 20 条"，超过会被拒绝或按 20 处理，大车系请用 `page` 翻页。
**Q: count 和 maxResult 有什么区别？**
`count` 是符合条件的总条数，`maxResult` 是当前页实际返回条数，翻页时二者要区分。
**Q: 缓存过期设多久合适？**
车型数据每周六 3 点更新，建议缓存 7 天并在周六更新后主动刷新，避免展示过期款型。
## 相关能力 / 下一步阅读
- [车型大全数据更新机制：每周六 3 点刷新与缓存时效设计](https://www.showapi.com/guides/car-model-data-freshness-1467)
- [车型大全免费调用与档位限制：如何避免触发额度限制](https://www.showapi.com/guides/car-model-free-tier-1467)
- **本系列共 12 篇**：查看[车型大全 API 指南总目录](https://www.showapi.com/guides/car-model-guides-1467)
