文档示例只代表「某次调用的样例」，不构成字段全集、类型契约、异常样例或版本承诺。以下对照表给出四个陷阱的触发场景与防御动作。
| 陷阱 | 典型表现 | 防御动作 |
| 示例 ≠ 全集 | 状态字段按示例写死三个分支，线上出现示例外枚举值直接抛异常 | 向文档要枚举全集；解析加兜底；新值落日志回补 |
| 示例 ≠ 契约 | 金额示例「元·字符串」，线上「分·整数」，结算差 100 倍 | 拿真实响应逐字段回填类型断言；换算独立成函数 |
| 示例 ≠ 异常样例 | 异常处理照想象写，业务失败也回成功码时解析崩 | 错误响应单独要样例（参数错/业务败/系统异常）单独测 |
| 示例 ≠ 最新版 | 接口加新必填字段，示例未同步，照抄即批量报错 | 接入核版本号；示例固化为自动化用例做漂移检测 |
陷阱一详解：枚举全集
示例为简洁只展示最常见值。代码按示例归纳分支，枚举扩充当日即故障。验收标准：每个枚举字段有文档全集依据；解析代码存在未知值兜底路径；未知值入日志并可按「未知态」流转，不中断业务。
陷阱二详解：类型与单位
金额（元/分、字符串/数字）与时间（时间戳/字符串、时区口径）是重灾区。此类差异沙箱不可测——示例与真实响应在外观层一致，仅类型层分岔。验收标准：单位换算与时间解析为独立函数并有边界用例；部署区域变更前后各验证一次。
陷阱三详解：错误响应结构
错误响应是独立结构。至少留存三类真实错误报文（参数错误、业务失败、系统异常）作为异常分支测试数据来源，异常处理不得由想象推导。
陷阱四详解：版本滞后
示例可能落后于接口升级（缺新必填字段）或早于字段废弃（含空值字段）。接入时核对示例版本号；运行中将文档示例固化为自动化用例，定期执行漂移检测。
示例漂移检测参考实现
DOC_EXAMPLE = { "amount": "100.00", "status": "PAID", "created_at": "2026-01-01 12:00:00", } KNOWN_STATUSES = {"PENDING", "PAID", "CLOSED", "REFUNDED", "PARTIALLY_REFUNDED"} def check_response(real: dict) -> list[str]: """拿真实响应对照示例逐字段体检，返回问题清单（空列表即通过）。""" problems = [] amt = real.get("amount") if isinstance(amt, str): problems.append(f"amount 是字符串({amt!r})：单位换算缺失") elif isinstance(amt, (int, float)) and amt > 100000: problems.append(f"amount={amt} 数量级异常：确认元/分口径") status = real.get("status") if status not in KNOWN_STATUSES: problems.append(f"status={status!r} 不在已知全集：需回补兜底分支") created = real.get("created_at") if isinstance(created, str) and "-" in created: problems.append(f"created_at={created!r}：确认时间口径与时区") return problems
每日定时以最新真实响应执行，问题清单非空即触发告警。
上线前检查清单（七项）
- 枚举字段有全集依据，解析含兜底
- 金额单位与类型已确认，换算独立成函数
- 时间格式与时区已确认，跨区域部署前已验证
- 三类错误响应样例已留存，异常分支有测试
- 示例版本号与调用版本已核对
- 示例已固化为自动化用例，有定时漂移检测
- 上线前以真实响应完成逐字段类型断言
