1. 接口契约概述

什么是接口契约

接口契约（Interface Contract）是服务提供方与消费方之间就 API 的输入、输出、行为、约束所达成的形式化约定。它不仅仅是接口文档，更是一组可验证、可执行、可版本化的规范定义。

为什么需要接口契约

在微服务架构中，后端团队往往并行开发多个服务。没有契约的协作会引发以下问题：

• 联调成本高：前后端、服务间依赖口头约定，接口变更频繁导致反复沟通。
• 测试不可靠：缺少契约校验，mock 数据与真实接口不匹配，集成测试形同虚设。
• 文档滞后：接口文档靠人工维护，代码更新后文档迅速过时。
• 版本混乱：没有契约版本管理，服务升级时无法判断兼容性。

契约驱动开发（CDD）概念

契约驱动开发（Contract-Driven Development, CDD）是一种以接口契约为核心的软件开发方法论。其核心流程为：先定义契约 → 再实现服务 → 最后验证一致性。

CDD 与传统开发模式对比

Go 后端中的契约载体

在 Go 微服务实践中，接口契约通常以以下三种形式存在：

• Protocol Buffers（protobuf）：适用于 gRPC 服务，契约文件以 .proto 格式定义，通过 protoc 生成 Go 桩代码。
• OpenAPI 3.0：适用于 RESTful API，契约文件以 yaml 或 json 格式定义，通过 oapi-codegen 生成 Go 服务端/客户端代码。
• Go 接口类型：适用于单体或内部包间调用，以 Go interface{} 作为契约，配合 mockgen 生成测试桩。

// 示例：protobuf 契约定义（user.proto）
syntax = "proto3";
package user.v1;

service UserService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  string user_id = 1;
  string name = 2;
  string email = 3;
}