二维码生成和识别：10 个实战避坑清单（100KB 上限 / 12h 清理 / 格式）
# 二维码生成和识别：10 个实战避坑清单（100KB 上限 / 12h 清理 / 格式）
> 接口/接入点：二维码生成和识别（apiCode=887，覆盖 887-1~887-4）· 是否免费：是 · 返回格式：JSON · 适用人群：已接入用户、一线开发 · 阅读时间：约 6 分钟
## 核心要点
- 10 条来自真实文档与一线踩坑：成功判据、12h 清理、100KB 上限、flag 拼写、base64 必传等。
- 本文是避坑汇总，逐项均链到对应详解文章。
## Why：把坑一次列全
分散在各篇的边界条件，这里集中成一张 checklist，上线前对照一遍，能挡掉大多数工单。
## 10 个避坑点
1. **成功判据用 `ret_code == "0"`**：不要依赖 `flag`（见[错误码排查](https://www.showapi.com/guides/qrcode-error-handling-887)）。
2. **flag 拼写不一致**：887-1 示例为 `ture`，887-2/3 为 `true`，勿做布尔判等（同上）。
3. **生成图每 12h 删除**：拿到 `imgUrl` 立即下载到自有存储（见[保存策略](https://www.showapi.com/guides/qrcode-save-strategy-887)）。
4. **只存 imgUrl 会失效**：生产必须落盘，别把临时链接当永久地址。
5. **887-2 上传 ≤100KB**：超限被拒，先压缩或改 887-3 传链接（见[三种识别对比](https://www.showapi.com/guides/qrcode-recognition-compare-887)）。
6. **887-3/887-4 文档未给大小上限**：自行限制入参，勿假设无限制。
7. **887-4 无 flag/msg**：只用 `ret_code` + `retText`，代码别取不存在字段。
8. **887-4 的 `imgData` 按必传**：文档标"否"但识别必须提供 base64。
9. **size 非连续枚举**：1-10 外加 16/20/30；长内容用大号会生成超大图（见[size 指南](https://www.showapi.com/guides/qrcode-size-guide-887)）。
10. **appKey 放 query 且勿泄露**：不要写死在前端；档位超限会失败（见[档位说明](https://www.showapi.com/free-api)）。
## How：上线前自检脚本（Python）
```python
def health_check(body):
warns = []
if body.get("ret_code") != "0":
warns.append("业务失败，检查 appKey/参数/档位")
if "imgUrl" in body:
warns.append("生成图 12h 内必须下载保存，勿长期直链")
if "flag" in body and body["flag"] not in ("true", "ture"):
warns.append("flag 异常，但请以 ret_code 判成功")
return warns
```
## 进阶 / 边界
- 免费接口有**档次限制**，大流量前评估调用量并兑换档位。
- 识别图片**清晰度**直接影响成功率，模糊/反光/畸变图优先换清晰源。
## FAQ
**Q1：这 10 条都来自文档吗？**
A：均来自接口文档与实测踩坑，未编任何文档外的参数或数字。
**Q2：哪条最容易导致线上事故？**
A：第 3 条（12h 清理）——只存 imgUrl 不落盘，用户后期扫码 404。
**Q3：大小上限数字我能自己设吗？**
A：887-2 的 100KB 是文档硬上限；887-3/4 文档未给，建议业务侧自设上限。
**Q4：有现成封装吗？**
A：可基于[返回字段全解](https://www.showapi.com/guides/qrcode-response-fields-887)与[错误码排查](https://www.showapi.com/guides/qrcode-error-handling-887)封装统一调用层。
## 相关能力 / 下一步阅读
- [二维码生成和识别：错误码与失败排查（ret_code 判据与 flag 拼写陷阱）](https://www.showapi.com/guides/qrcode-error-handling-887)
- [二维码生成和识别：图片每 12 小时清理，如何设计保存与缓存策略](https://www.showapi.com/guides/qrcode-save-strategy-887)
- [二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）](https://www.showapi.com/guides/qrcode-recognition-compare-887)
- **本系列共 12 篇**：查看[二维码生成和识别指南总目录](https://www.showapi.com/guides/qrcode-guides-887)
