接口契约驱动开发强调将接口作为协作协议，通过清晰职责边界、业务语义命名、约束性参数/返回值、协作导向JavaDoc、default/static方法封装通用逻辑及Spring Cloud Contract验证，实现上下游预期对齐与可执行契约保障。
接口契约驱动开发，核心是把接口当成“协作协议”来写，而不是当作技术模板来堆方法。它不靠运行时检查，而是靠定义清晰的职责边界、行为约束和协作规则，让上下游开发者在编码前就对齐预期，减少返工和集成踩坑。
用接口名和方法签名锁定业务语义
接口不是技术容器，而是业务能力的具象化表达。命名要直指职责，比如 OrderValidator 比 IOrderService 更能传递“只做校验，不处理流程”的契约；方法签名只保留必要信息，不暴露实现细节。
- ✅ 接口定义示例：boolean isValid(PaymentRequest request); —— 明确输入、输出和判断意图
- ❌ 避免：public abstract boolean isValid(PaymentRequest request) throws Exception; —— public abstract 冗余，Exception 太宽泛，掩盖真实失败场景
- 方法参数和返回值需带业务含义约束，比如 @param amount 支付金额，精度两位小数，必须 > 0
JavaDoc 写成协作协议，不是使用说明
接口级和方法级 JavaDoc 要回答“谁调用、为什么调用、调用后能信什么”，而不是“怎么用”。它面向的是协作者，不是使用者。
- 接口文档注明角色定位，例如：@description 用于支付通道前置风控，不参与资金结算
- 每个方法标注业务级前置条件（如“订单状态必须为 CREATED”）、后置保证（如“返回 true 表示已通过所有规则，不含人工复核”）和明确异常（如 @throws RiskThresholdExceededException 当风险分超过阈值时抛出）
- 避免写“本方法用于校验”，而要写“本方法执行实时反欺诈规则集 v2.1，响应延迟 ≤80ms（P95）”
用 default/static 方法封装可复用的契约逻辑
default 方法不是“偷懒加实现”，而是把契约中通用但允许覆盖的部分显式声明出来，比如幂等控制、基础日志、格式预检。static 方法则适合无状态工具逻辑，如 JSON 解析或 ID 生成。
立即学习“Java免费学习笔记（深入）”；
- default 方法需标注 @implSpec，说明适用边界：“本默认实现基于本地缓存，分布式部署时请重写”
- static 方法不参与多态，适合提供契约配套能力，例如 fromJson(String json)，让调用方无需引入额外工具类
- 两者都应保持轻量，不引入外部依赖或复杂状态，否则就违背了“契约应简单、稳定、可替换”的原则
配合 Spring Cloud Contract 做消费者驱动验证
当接口跨服务时，光靠 JavaDoc 不够。Spring Cloud Contract 让消费者定义期望的 HTTP 请求/响应、消息结构和错误场景，自动生成双方测试用例和 Stub，把契约从文档落地为可执行验证。
- 消费者编写 Groovy 或 YAML 契约文件，描述“我发什么、期待什么、异常怎么返回”
- 构建时自动生成：服务提供者的单元测试（确保实现符合契约）、消费者的 Stub Server（用于联调隔离）
- 契约变更触发 CI 失败，强制双方同步协商，避免“上线才发现字段名不一致”这类低级问题
