接口契约需用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），避免消费方因命名差异产生理解偏差
