Java接口契约需以OpenAPI 3.0显式定义，统一响应模型与错误码体系，由网关强制校验，并通过版本化、自动化测试保障向后兼容。
在分布式系统中，Java 接口要真正发挥契约作用，关键不是写几个注解或返回 JSON，而是让接口定义本身成为多方（前端、后端、测试、网关、SDK 生成器）共同遵守的“法律文件”。这需要从设计源头就嵌入标准化、可验证、可演进的契约机制。
用 OpenAPI 3.0 定义机器可读的接口契约
不能只靠 Java 注解“暗示”行为，而要用 OpenAPI（原 Swagger）YAML/JSON 显式声明。Spring Boot 可通过 springdoc-openapi 自动从 @RestController 和注解推导，但强烈建议反向驱动：先写 OpenAPI 文件，再生成服务骨架或客户端 SDK。
- 每个
path明确对应资源路径（如/api/v2/orders），不带动词 -
operationId唯一且语义清晰（如getOrderById），用于生成 SDK 方法名 - 为每个请求/响应定义
schema，包括必填字段、格式（email、date-time）、枚举值和示例 - 明确标注
400（参数校验失败）、404（资源不存在）、409（冲突）等业务相关状态码及对应响应体结构
统一响应体与错误模型，消除“各说各话”
分布式环境下，不同团队实现的微服务若返回五花八门的 JSON 结构（有的用 data，有的用 result，有的错误塞在 message 字段里），前端就必须写一堆适配逻辑——这直接破坏契约价值。
- 定义全局标准响应类，如
ApiResponse<T>，固定包含code（数字错误码）、message（用户提示）、data（业务数据）、timestamp - 错误码体系分层：1xx（信息）、2xx（成功）、4xx（客户端问题）、5xx（服务端问题），公司级统一注册管理
- 所有异常必须被全局
@ControllerAdvice捕获并转换为标准响应，禁止裸 throw 或直接返回原始异常堆栈
通过 API 网关统一执行契约守门人职责
单靠开发自觉难以保障契约落地。API 网关（如 Spring Cloud Gateway、Kong）应成为强制执行层：
立即学习“Java免费学习笔记（深入）”；
- 路由前校验请求是否符合 OpenAPI 中定义的 path、method、query/header 参数格式和必填性
- 对请求 body 做 JSON Schema 验证（非简单非空），拦截字段类型错误、枚举越界等
- 响应返回时自动注入
X-Api-Version、X-RateLimit-Limit等标准化头，并过滤敏感字段（如password） - 将 OpenAPI 定义同步至网关配置，实现“契约即配置”
契约变更需版本化 + 向后兼容 + 自动化检测
接口升级是常态，但随意改字段、删接口会引发雪崩。契约演进必须受控：
- URI 版本化优先（
/api/v2/users），避免通过 Header 或参数传递版本号，降低客户端复杂度 - 新增字段默认可选，删除字段必须保留旧字段别名至少一个大版本周期
- 接入契约测试工具（如 Pact、Spring Cloud Contract），每次构建自动运行消费者驱动合约测试，确保提供方变更不破坏已签约消费者
- OpenAPI 文件纳入 Git 仓库，配合 CI 流水线检查：新增 endpoint 是否有文档、状态码是否全覆盖、schema 是否有效
