适用范围
约束所有变更类操作的幂等身份、重放窗口与冲突处理。
不约束：只读接口；幂等身份的生成算法；存储实现。
规范条款
幂等身份
- 每个变更类操作必须有幂等身份，且必须由调用方生成。
- 幂等身份必须满足：每次尝试唯一、不跨进程复用、在重放窗口内稳定。
- 幂等身份必须位于请求语义内；必须不仅存在于传输头（必须遵循API 与传输）。
- 服务端必须在应用任何变更之前完成幂等判定。
重放语义
- 同幂等身份 + 同规范化请求体 → 必须返回同一结果，且必须不重复应用变更。
- 同幂等身份 + 不同请求体 → 必须冲突失败，必须不执行任一版本。
- 规范化必须有确定规则（字段顺序、空值、等价表示），且必须在文档中声明依据。
- 重放必须返回冻结的原响应或等价结果；必须不因当前状态变化而返回不同语义。
重放窗口
- 每个可能返回"无工作"类结果的接口必须声明有界重放窗口；必须不承诺无限期重放。
- 窗口内同身份重放必须得到同一回答；窗口外必须要求调用方换新身份。
- 窗口长度必须是显式声明的参数（必须遵循非功能基线的统一口径）。
冲突与优先级
- 冲突必须分类且必须给出明确优先级：
| 冲突 | 优先级 | 必须的行为 |
|---|
| 期望修订不符（状态冲突） | 高 | 本次提交未生效；先同步当前状态 |
| 结果冲突（已存在不同终态） | 高 | 停止；不得覆盖 |
| 身份 / 租约冲突 | 高 | 不抢占；失约方先收束 |
| 同身份异内容 | 中 | 冲突失败，不执行任一版本 |
- 必须不存在"后写覆盖先写"的路径；正确性必须靠期望修订或幂等身份保证。
跨系统一致性
- 涉及外部副作用的操作必须保留确定性的业务操作标识，用于对账与去重。
- 副作用已发出但确认丢失时，必须先对账再决定是否重做；必须不因"本次是新运行"就重复不可逆副作用。
- 不可核对或不可逆的操作必须标记为需要人工处理，必须不进入自动重试。
自动重试
- 自动重试必须只覆盖窄类操作：只读类、上游支持幂等键的写类、能通过稳定逻辑键接管既有结果的写类。
- 逻辑键必须基于业务要素（作用域 + 对象 + 动作 + 输入标识 + 效果类型）；必须不只基于本次执行的标识。
- 必须不存在无限自动重试；必须有次数或时间上界，且上界必须显式声明。
违反时的失败语义
| 违反情形 | 必须的行为 |
|---|
| 变更类操作无幂等身份 | 视为规格违反；评审阶段必须拦截 |
| 幂等判定晚于变更 | 必须改为变更前判定 |
| 同身份异内容被执行 | 视为规格违反 |
| 承诺无限重放 | 必须改为有界窗口 |
| 后写覆盖先写 | 必须改为期望修订保护 |
| 不可逆操作进入自动重试 | 必须移出并标记人工处理 |
校验方式
| 校验对象 | 判据 | 失败表现 |
|---|
| 幂等完备 | 每个变更类操作必须能定位到幂等身份来源 | 缺失即失败 |
| 重放不变更 | 同身份同体重放不得产生第二次变更 | 产生即失败 |
| 异体冲突 | 同身份异体必须冲突且不执行 | 执行即失败 |
| 窗口边界 | 窗口外同身份重放必须被拒绝或要求换身份 | 仍接受即失败 |
| 冲突优先级 | 构造状态冲突与结果冲突，行为必须与优先级表一致 | 不一致即失败 |
| 覆盖防护 | 以陈旧修订提交必须失败 | 成功即失败 |
| 对账要求 | 不可逆操作必须能定位到业务操作标识 | 缺失即失败 |
| 自动重试上界 | 必须有显式次数或时间上界 | 无上界即失败 |
相关规格