contracts

合约

将跨边界接口视为承诺，其有效期可能长于当前编辑。

识别合约

更改边界之前，先明确合约及其使用方：

• HTTP、RPC、GraphQL 或 CLI 请求与响应。
• 数据库架构、迁移输出或持久化数据结构。
• 事件、队列消息、Webhook 或后台任务负载。
• 公共模块导出或软件包 API。
• 配置、环境变量、功能标志或文件格式。
• UI 路由、URL 结构或外部可见行为。

如果当前仓库之外可能存在调用方，就应假设兼容性至关重要。

对变更分类

实施前先对合约变更分类：

• 增量式：新增可选字段、新端点、新枚举值或新功能，但不改变现有含义。
• 收窄式：拒绝输入、移除状态、收紧验证规则或减少可接受的行为。
• 破坏式：移除、重命名、重新定义类型、调整顺序，或改变现有字段或行为的含义。
• 语义式：结构不变，但可观察到的含义发生变化。

增量式变更通常最安全。收窄式、破坏式和语义式变更需要明确的迁移或兼容性计划。

保持兼容性

优先采用能保持兼容性的方案：

• 先添加，再移除。
• 在迁移期间同时读取旧结构和新结构。
• 确认旧读取方不再存在后，再只写入新结构。
• 如果无法保持行为兼容，则为外部使用的 API 添加版本。
• 除非严格校验本身就是合约的一部分，否则应容许未知字段。
• 说明默认值以及字段缺失时的行为。

除非能证明另一侧不受影响，否则不要只更新生产方或只更新消费方。

测试边界

在使用方能够观察到合约的边界处验证：

• 针对公共 API 和事件的合约测试。
• 针对持久化数据的迁移测试。
• 针对编码/解码或导入/导出的往返测试。
• 针对旧负载或架构的兼容性测试样例。
• 工具链支持时，进行类型或架构检查。

内部单元测试不足以证明合约仍然兼容。

完成标准

已明确合约并考虑其使用方，已对变更分类；对于收窄式、破坏式或语义式变更，已明确处理兼容性或迁移；已检查生产方和消费方受到的影响；并且验证覆盖了依赖方可观察到的边界。