微服务接口是服务间契约，需契约优先（contract-first），用openapi或protobuf前置定义并纳入git管理，驱动mock、sdk、契约测试与文档生成；版本控制须由基础设施识别，推荐路径前缀；兼容性靠机制保障，含可选字段、不删改字段、dto隔离及语义化版本；契约验证须嵌入ci/cd闭环。
接口在微服务中不是简单的函数调用入口，而是服务之间明确约定的契约。它定义了“谁能调用、怎么调用、传什么、返回什么、出错怎么报”，直接决定服务能否独立演进、协同稳定运行。
契约必须前置定义，而非事后补文档
契约优先（Contract-First）是微服务协作的基础。理想做法是在编码前就用 OpenAPI 3.0 或 Protocol Buffers 完整描述接口：包括路径、方法、请求体结构、响应体字段、状态码含义、错误码枚举。这份契约文件应纳入 Git 管理，并作为以下环节的唯一源头：
- 自动生成 Mock Server，供前端或下游服务并行开发
- 驱动客户端 SDK 自动生成（如 Swagger Codegen、grpc-gateway）
- 嵌入 CI 流水线，用 Dredd 或 Pact 执行运行时契约测试，验证实现是否偏离定义
- 统一生成 API 文档，避免代码与文档不同步
版本控制要落地到基础设施可识别的层面
仅靠代码注释或内部约定无法保障多团队协同。真正有效的版本控制需被网关、代理、缓存、监控等基础设施识别和路由。路径前缀（如 /v1/users、/v2/users）是最稳妥的选择：
- Nginx、Envoy、Kong 等网关天然支持按路径分流，无需额外解析 header
- 日志、链路追踪、指标聚合可直接按版本维度切分，便于问题定位
- 客户端 URL 明确，调试、测试、压测都直观可靠
- 禁止在 handler 内部用 if 判断 version 字段，必须通过路由分组隔离不同版本的实现逻辑
兼容性不是靠口头承诺，而是靠机制保障
向后兼容不能依赖开发者自觉。关键实践包括：
- 新增字段默认设为可选，不破坏旧客户端解析
- 绝不删除已有字段或修改其语义；如需淘汰，先标记 deprecated 并保留至少一个大版本周期
- 使用 DTO 隔离内部模型与对外契约，避免数据库字段变更直接暴露给 API
- 对重大变更（如资源结构重设计），必须同时运行新旧版本服务，并设定明确的废弃时间表
- 用语义化版本号（SemVer）管理接口包本身：主版本升级意味着不兼容变更，下游服务需显式升级依赖
契约验证要进入交付闭环
没有自动验证的契约等于没有契约。建议在 CI/CD 中固化以下步骤：
- 提交 PR 时，校验 OpenAPI 文件语法合规性（如用 Speccy）
- 构建阶段，基于契约启动 Mock Server 并运行消费者端契约测试（Pact Consumer Test）
- 部署前，在预发环境执行 Pact Provider Verification，确认服务实现完全满足所有消费者契约
- 失败即阻断，不妥协
