04 第4周D20 项目开发第3天
D20 项目开发 · 第 3 天：契约自测与修复
D20 项目开发 · 第 3 天：契约自测与修复
项目期。今日目标：每个模块对照 D17 契约文档自测，找出字段/状态码/幂等的偏差并修复，为明天集成联调清零已知问题。
今日目标（对应作业.md 检查点）
- 全员：对照契约文档做一遍接口自测，把偏差列出来并修完。
- A：verify/deduct 的调用参数与 B 实测返回完全一致。
- B：三组接口（internal/admin）按契约自测通过，幂等二次验证 OK。
- C：四个页面与 B 返回字段完全对得上（没有"前端读的字段后端没返回"）。
- D：联调脚本在 compose 全栈上跑通（充值→调用→断言）。
自测方法
- 用 curl 打每个契约接口，逐字段核对（D3 的 curl -v 用上）。
# 示例：B 的 verify 自测
curl -s http://localhost:8081/internal/verify \
-H "Content-Type: application/json" \
-d '{"api_key":"sk-正确key"}' # 期望 valid=true, balance=...
curl -s http://localhost:8081/internal/verify \
-d '{"api_key":"sk-错的"}' # 期望 valid=false- 契约核对表：接口 | 输入字段 | 输出字段 | 状态码 | 幂等性。每个接口一行，勾掉即达标。
- 偏差处理：小偏差直接修；大分歧（要改契约字段）→ @全员 + 更新 D17 契约文档。
常见问题预排（今天大概率遇到）
| 问题 | 处理 |
|---|---|
| 前端字段名和后端不一致 | 以契约为准，改代码不改契约（除非全体同意） |
| deduct 重复扣费 | 查幂等实现；用同 request_id 打两次验证 |
| 余额不足还返回 200 | verify/deduct 要有明确"余额不足"语义 |
| 流式下 deduct 时机不确定 | 以 usage 返回为准，别提前扣 |
| compose 里服务互访不了 | 用服务名 + 端口，检查 compose 网络 |
站会（早上 5 分钟）
- 昨天各自哪里通了/哪里卡 / 今天自测计划 / 有无契约分歧要提。
讲解节奏建议（站点指导）
| 时段 | 安排 |
|---|---|
| 09:00-09:20 | 站会 + 自测方法演示（怎么用 curl 核对一个接口） |
| 09:20-12:00 | 各人自测 + 修复 |
| 13:30-16:30 | 继续自测/修复 + 交叉复核（A 测 B，B 测 C 的字段） |
| 16:30-17:00 | 收口：统计"还有哪些已知偏差未修"，明天联调从这开始 |
常见误区汇总
| 误区 | 正确理解 |
|---|---|
| 代码"看起来对"就行 | 必须 curl 实测，字段逐字核对 |
| 前端字段不一样就改后端 | 以契约为准；改契约要全体同意 |
| 自测只测成功路径 | 无效 key/余额不足/重复 request_id 也要测 |
| 今天就把所有问题修完 | 目标是"清零已知问题"，新问题明天联调暴露 |
| 不用工具就靠肉眼 | 用 curl/脚本断言，把自测写成可重复的命令 |