身份证归属地查询：用 Redis 缓存降低重复查询与频率限制风险
# 身份证归属地查询：用 Redis 缓存降低重复查询与频率限制风险
> 接口：身份证归属地查询（apiCode=25，接入点 25-3） · 免费 · POST/GET · JSON · 适用人群：中高级开发者、架构师 · 阅读时间：约 6 分钟
## TL;DR
- 同一个身份证号，户籍地区/生日/性别**不会变**，结果天然可缓存。
- 以 `idcard:25:<身份证号>` 为 key 缓存，可省重复调用、降频率、提性能。
- 注意缓存穿透/雪崩的基本防护。
## Why
在实名核验、批量导入等场景里，同一批用户会被反复查询，或同一身份证在多次业务流程中被多次调取。每查一次就发一次请求，既浪费调用额度、又可能触发平台频率限制。由于身份证的户籍信息长期稳定，把结果缓存起来是收益最高的优化。
## What
| 项 | 说明 |
|----|------|
| 缓存 key | `idcard:25:<身份证号>` |
| value | `retData`（address/birthday/sex）或整段业务返回 |
| 适用前提 | 结果稳定、幂等；免费接口仍受频率约束 |
## How
### 步骤 1：先查缓存，未命中再调接口
```python
import json
import redis
import requests
r = redis.Redis(host="localhost", port=6379, db=0)
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/25-3"
def get_idcard(id_number: str) -> dict:
key = f"idcard:25:{id_number}"
cached = r.get(key)
if cached:
return json.loads(cached)
resp = requests.post(URL, params={"appKey": APP_KEY},
data={"id": id_number}, timeout=10)
data = resp.json()
if data.get("showapi_res_code") != 0 or data["showapi_res_body"].get("ret_code") != 0:
raise RuntimeError("查询失败")
rd = data["showapi_res_body"]["retData"]
# TTL 设为较长（如 30 天）；户籍信息极难变动
r.set(key, json.dumps(rd, ensure_ascii=False), ex=30 * 86400)
return rd
```
### 步骤 2：防穿透
对非法/不存在的号码，也缓存一个"空结果"短 TTL，避免恶意或异常号码反复击穿到接口。
## 返回示例
缓存的 value 即 [返回字段全解](https://www.showapi.com/guides/idcard-attribution-fields-25) 中的 `retData`：`{"address": "...", "birthday": "...", "sex": "..."}`。
## 进阶 / 边界
- **TTL 选择**：户籍地区/生日/性别基本不变，可设较长 TTL（如 30 天~1 年）；若你业务要求"每次以接口为准"，则缩短或加主动失效。
- **雪崩防护**：批量预热时给 TTL 加随机抖动，避免同一时刻集中过期。
- **缓存与源一致性**：本接口结果稳定，一致性风险低；若未来接口逻辑变化，按 key 前缀批量清缓存即可。
- **仍要限速**：缓存未命中时的突发并发，参考 [批量核验](https://www.showapi.com/guides/idcard-attribution-batch-25) 的限速写法。
## FAQ
**Q：缓存多久合适？**
户籍信息（籍贯/生日/性别）几乎不变，可设较长 TTL（如 30 天以上）；若需"每次以接口为准"则缩短。本文不规定固定值，按你的业务容忍度定。
**Q：缓存会把错误结果也存进去吗？**
不应。只在 `ret_code == 0` 成功时才写入缓存；失败走重试/降级，不缓存。
**Q：免费接口为什么还要缓存？**
免费不等于无限频。缓存能降低请求频次、规避平台频率限制，同时提升响应速度。
**Q：key 里放身份证号会不会泄露？**
Redis 属内部存储，应做好访问控制与加密；也可对号码做哈希后再作为 key，降低明文暴露。
**Q：批量导入时怎么用缓存？**
先查缓存，命中直接用；未命中再调接口并回写。配合 [批量核验](https://www.showapi.com/guides/idcard-attribution-batch-25) 效果最佳。
## 相关能力 / 下一步阅读
- [身份证归属地查询：批量核验（Excel/CSV 导入）的循环调用设计](https://www.showapi.com/guides/idcard-attribution-batch-25)
- [身份证归属地查询：返回字段全解（retData / address / birthday / sex 与系统级结构）](https://www.showapi.com/guides/idcard-attribution-fields-25)
- [身份证归属地查询：错误处理与排错（showapi_res_code / ret_code 通用处理）](https://www.showapi.com/guides/idcard-attribution-errors-25)
- **本系列共 12 篇**：查看[身份证归属地查询指南总目录](https://www.showapi.com/guides/idcard-attribution-guides-25)
