稳定 API 的三个边界：
输入、时间与重复请求

API 是系统之间的契约，也是故障传播最常经过的边界。大量线上问题并非复杂算法导致，而是模糊输入、无限等待或一次请求被执行了多次。把这三件事设计清楚，能消除很大一部分不确定性。

一、输入边界：拒绝模糊

校验不应只判断字段是否为空，还要覆盖长度、范围、格式、字段间关系和业务状态。更重要的是，错误响应要稳定：使用一致的错误码、可定位字段和面向调用方的说明，而不是把数据库异常直接暴露出去。

• 在入口完成语法校验，尽早失败。
• 在领域层完成业务约束校验，避免规则散落。
• 限制请求体、数组长度和分页大小，保护资源上界。

对于版本演进，新增可选字段通常安全；修改字段含义或复用旧枚举值则风险更高。契约测试能在发布前发现调用方与服务方理解不一致的问题。

二、时间边界：每一跳都有预算

没有超时的网络请求，本质上把系统资源交给外部依赖无限占用。合理的做法不是给所有请求统一设置 30 秒，而是从用户允许的总时长反向分配预算。

下游超时必须短于上游剩余预算。重试也会消耗预算，只适用于短暂故障，并应配合指数退避和随机抖动。对非幂等操作盲目重试，可能把一次超时变成两次扣款或两条订单。

三、重复边界：让重试可以安全发生

移动网络切换、网关重试和客户端超时都可能造成重复请求。关键写操作可以要求调用方提交幂等键，服务端将幂等键、请求摘要和处理结果一起保存。在有效期内遇到相同请求，直接返回原结果。

幂等键相同但请求内容不同，应该明确拒绝；正在处理中的请求，可以返回“处理中”状态，而不是并发执行。数据库唯一约束通常是最后一道可靠防线，不能只依赖进程内锁。

边界之外：可观测、可降级

边界设计仍需配合可观测性。记录耗时阶段、重试次数、下游错误类别与幂等命中率，可以帮助团队发现预算是否合理。当依赖失效时，优先返回明确、有限的降级结果，避免故障层层放大。

稳定性不是“永不失败”，而是失败发生时范围有限、行为可预测、恢复有路径。