接口契约需用OpenAPI 3.0或Protocol Buffers前置定义，涵盖路径、参数、响应、错误码等，并提交Git主干；驱动Mock、SDK生成、契约测试与文档；版本通过路径前缀管理，禁止破坏性变更；跨语言统一落地，字段命名体现业务语义。

接口在微服务架构中定义契约，核心是把“双方怎么说话”变成可验证、可管理、可演进的机器可读约定，而不是靠文档或口头沟通。

用标准格式前置定义，不写代码先定契约

必须在开发前就用 OpenAPI 3.0（REST 场景）或 Protocol Buffers（gRPC 场景）完整描述接口行为。一份契约文件要明确：

• 路径、HTTP 方法或 RPC 方法名
• 请求参数类型（路径、查询、Header、Body），含字段名、是否必填、数据类型和示例
• 所有可能响应的状态码、对应响应体结构（用 JSON Schema 或 proto message 定义）
• 错误码枚举与语义说明（比如 40001 表示“用户余额不足”，不是只写“参数错误”）

这份文件必须提交到 Git 主干分支，作为唯一信源——没有它，就不允许新增接口；修改它，必须走 PR 流程并自动校验语法与兼容性。

契约要能驱动工程活动，不能只看不用

契约不是静态文档，而是流水线里的“活零件”：

• 自动生成 Mock Server，供前端或下游服务并行开发
• 用 openapi-generator 或 protoc 自动生成客户端 SDK 和服务端骨架代码
• 嵌入 CI/CD：用 Dredd 或 Pact 执行运行时契约测试，验证实现是否偏离定义
• 生成实时 API 文档（如 Swagger UI），且内容与代码完全一致

版本控制必须由基础设施识别，不能靠人猜

接口升级必须显式标识版本，并让网关、注册中心、SDK 等基础设施能自动识别：

• 推荐用路径前缀方式（如 /v2/orders），比 Header 或参数更直观、更易监控
• 禁止删除字段或修改字段类型；新增字段默认设为可选；废弃字段加 deprecated: true 并保留至少一个大版本
• 使用语义化版本（如 1.2.0 → 2.0.0），配合 diff 工具在 PR 阶段自动标出 BREAKING 变更

跨语言、跨团队的契约要统一落地形式

契约最终要被消费方真正用上，不能停留在后端内部：

• 前端必须能 import { UserResponse } from '@shared/types'，这个 interface 来自契约生成，不是手写
• 若某模块无 TypeScript 支持，至少提供配套的 JSON Schema 或 OpenAPI 文件，作为等价契约
• 所有字段命名体现业务语义（如 userName 而非 user_name），避免消费方因命名差异产生理解偏差