设计模式 - 契约式设计原则（Design by Contract, DbC）最佳实践

一、引言：新时代的“集装箱”——接口

在现代微服务与分布式系统中，接口已成为团队协作与系统集成的通用标准。然而，常见的接口风险：

• 多余参数：接口接收了未定义的字段，导致应用崩溃；
• 格式不符：返回数据结构与文档不一致，消费端解析失败；
• 部署不一致：分布式多节点漏部署某个版本，数据处理出现分歧。

要在“自由灵活”与“契约约束”之间找到平衡，契约式设计原则（Design by Contract, DbC）正是我们在 API 设计中的指导书。

二、契约原则概述

契约原则将 API 看作“客户—供应商”之间的合同，在设计时定义：

1. 预置条件（Preconditions）：调用者必须满足的输入约束；
2. 不变条件（Invariants）：在处理过程或多副本间需保持一致的共享状态；
3. 后置条件（Postconditions）：调用完成后输出需满足的规范。

这种“责任与义务”的分明，让使用者和提供者都清楚：

“只要你满足了输入前提，我就负责给你正确且一致的结果。”

三、为什么要用契约原则指导 API 设计

1. 降低沟通成本：预先声明输入输出格式和协议（如 REST+JSON），使用者无需二次询问；
2. 增强独立性：契约将实现细节隔离，客户端只依赖规范，不关心内部变化；
3. 提升可用性承诺：契约意味着要保证高可用—输入校验、内部容错与一致性部署都在责任范围内。

四、三大关键问题与契约三要素

只要回答好“三问”，接口契约就基本完善。

五、六大 API 设计技巧

1. 职责分离（接口隔离）

   • 每个 API 只承载单一职责，避免功能混合带来的相互影响。
   • 例如：修改商品价格、修改库存、修改优惠，应该拆分为三个独立接口。

2. 命名要直观一致

   • 全部小写英文、常用缩写、语义自解释。
   • 例：GET /api/v1/users（列出用户），POST /api/v1/orders/{id}/cancel（取消订单）。

3. 错误码尽量少自定义

   • 遵循 HTTP 状态码语义，错误信息写在 message 字段；
   • 避免用如 404 表示“未授权”等自定义冲突。

4. 接口幂等性

   • GET、PUT、DELETE 自然幂等；POST 可通过唯一键、分布式锁、Source+Token、状态机等方式实现。
   • 例：支付接口使用 orderId+clientToken 共同做幂等检查。

5. 安全策略分层

   • 内部 API：严格输入校验与异常处理；
   • 外部 API：额外加鉴权限流、WAF 或 API 网关防护，拒绝无效请求并返回明确错误。

6. 版本管理

   • URI 版本号：/v1/resource vs /v2/resource；
   • 并行服务：或通过 API 网关路由到不同版本；
   • 提前规划淘汰时间窗口，通知使用者平滑迁移。

六、总结

契约原则为 API 设计提供了三要素+六技巧的系统方法，帮助我们在自由与约束之间找到平衡：

• 三要素：预置、不变、后置，回答“期望、保证、保持”；
• 六技巧：职责分离、命名、错误码、幂等、安全、版本管理。