这类问题看似集中在一个 API 或参数上，真正决定可用性的却是状态归属、资源上限和失败后的恢复方式。 JSON 忽略未知字段通常安全，但把字段从秒改毫秒或重新解释 null 会在类型不变时静默出错。schema 文档必须包含语义与单位。
API 契约不仅是字段类型，还包括单位、缺省语义、幂等性、错误分类和版本窗口。客户端必须能区分可重试、需用户操作与永久拒绝，避免统一重试制造副作用。
先把实现决策说清楚
落地时要把关键选择变成稳定契约：输入如何校验、状态由谁推进、资源何时释放、旧版本如何降级。只有这样，后续优化才不会改变原有语义。
- 只追加可选字段并给默认行为，枚举接收 unknown 分支；破坏变化用新字段或版本，旧字段经过至少一个观测弃用周期再删除。
- 所有输入都设置大小、次数和时间预算，并在超限时返回可操作的稳定错误码。
- 上线参数必须有保守默认值、服务端上限和灰度开关，不能把浏览器传来的数字直接当作资源预算。
“API Schema 演进：新增字段容易，改变语义最危险”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
最容易漏掉的失败路径
边界条件会把隐藏假设变成真实事故。弱网、刷新、并发和容量上限必须组合测试，因为单独出现时它们往往都能被重试掩盖。
- 服务端新增枚举值让旧客户端 switch 进入 unreachable 崩溃；复用同字段表达相反语义会让灰度期两端各自“正确”。
- 只修正界面状态而没有清理底层资源，下一次操作继承队列、锁或过期凭据并再次失败。
- 指标标签直接包含用户或任务标识，既制造高基数成本，也让诊断数据泄露不必要的身份信息。
上线前怎样验证
验证时同时观察两端状态、持久化记录和可观测指标。单看某个按钮或一次接口响应，无法证明整个闭环成立。
- 保存当前和过去客户端 payload 作为消费者契约，针对新旧双向组合运行，未知字段、枚举与缺失字段都要有稳定结果。
- 在操作中途断网、切换网络并恢复，核对两端状态、持久化记录和资源计数最终一致。
- 分别覆盖直连、中转、弱网、后台标签页和移动端，报告不能只给平均值或一次成功截图。
最终结果应同时满足正确性、可恢复性和可解释性。任何一项只能依赖刷新页面或工程师猜测，都说明协议闭环仍不完整。