4. 契约驱动设计(CDD)：契约优先的开发流程，接口作为服务间的“合同”

在 BFF 架构中，多个团队（前端、BFF、后端）并行开发是常态。如果没有明确的“合同”，接口的变更会频繁导致集成失败。契约驱动设计（Contract-Driven Design, CDD）正是为了解决这一问题：先定义契约，再实现代码。契约是服务间通信的“法律条文”，任何一方的变更都必须遵守契约条款。

4.1 契约优先 vs. 代码优先

传统开发流程通常是“代码优先”：后端先写 API，前端再对接。这种方式在微服务与 BFF 场景下容易导致接口定义模糊、文档滞后、联调成本高。契约优先将契约作为开发起点，所有实现都围绕契约展开。

4.2 CDD 核心流程：契约驱动开发五步法

契约驱动开发不是一次性活动，而是一个持续迭代的闭环。以下五步法适用于 BFF 与下游微服务之间的接口定义：

1. 契约设计（Design）：BFF 团队与前端、后端团队共同定义接口契约，包括请求/响应结构、状态码、错误格式、限流策略等。
2. 契约评审（Review）：所有相关方对契约进行评审，确保语义正确、边界清晰、无歧义。评审通过后，契约进入“冻结”状态。
3. 契约发布（Publish）：将契约文件发布到内部注册中心或共享仓库，供所有团队拉取。同时自动生成 Mock Server 和测试桩。
4. 并行开发（Develop）：前端、BFF、后端基于同一份契约并行开发，各自使用 Mock 数据进行联调，无需等待对方完成。
5. 契约验证（Verify）：在 CI/CD 流水线中，对实际接口进行契约一致性验证，确保实现与契约完全匹配。验证不通过则阻断发布。

4.3 契约作为“合同”的三大要素

一份合格的接口契约，必须包含以下三个维度的约束，缺一不可：

4.4 Go 语言中的契约实现：以 Protobuf 为例

在 Go 生态中，Protobuf 是契约驱动开发的典型工具。契约文件（.proto）定义了服务接口和消息结构，然后通过 protoc 编译器生成 Go 代码、Mock 桩、文档等。

以下是一个 BFF 与用户服务之间的契约示例：

syntax = "proto3";

package user.v1;

option go_package = "github.com/example/bff/contracts/user/v1;userv1";

// 用户服务契约
service UserService {
  // 获取用户基本信息（BFF 聚合场景常用）
  rpc GetUser(GetUserRequest) returns (GetUserResponse);

  // 批量获取用户（用于首页推荐列表）
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
}

message GetUserRequest {
  string user_id = 1;      // 必填，UUID 格式
  string fields = 2;       // 可选，指定返回字段，如 "id,name,avatar"
}

message GetUserResponse {
  string user_id = 1;
  string name = 2;
  string avatar_url = 3;
  int64 created_at = 4;    // Unix 时间戳
  // 语义契约：如果用户不存在，返回空 response，错误码在 gRPC status 中体现
}

message ListUsersRequest {
  repeated string user_ids = 1;  // 最多 100 个
  int32 page_size = 2;           // 默认 20，最大 100
  string page_token = 3;         // 分页游标
}

message ListUsersResponse {
  repeated GetUserResponse users = 1;
  string next_page_token = 2;
  int32 total_count = 3;
}

4.5 契约验证：自动化守护“合同”

契约验证是 CDD 流程的最后一道防线。在 CI 流水线中，我们需要验证实际运行的接口是否与契约文件完全一致。常用的验证策略包括：

• 静态验证：检查生成的代码是否与契约文件同步（如 git diff 检测 .proto 文件变更后是否重新生成代码）。
• 动态验证：启动服务实例，发送预定义的请求，验证响应结构、状态码、错误格式是否与契约匹配。
• 消费者驱动契约验证（CDC）：由消费者（如 BFF 前端）定义期望的交互，验证提供者（如后端微服务）是否满足这些期望。常用工具：Pact、Spring Cloud Contract。

4.6 CDD 在 BFF 团队中的落地要点

• 契约仓库独立：将契约文件放在独立的 Git 仓库中，BFF、前端、后端团队都通过子模块或包管理工具引用，避免拷贝导致的版本混乱。
• 契约版本化：使用语义化版本（SemVer）管理契约，主版本号变更意味着不兼容的接口改动，需要所有消费者同步升级。
• Mock 优先：契约发布后，立即生成 Mock Server，让前端和 BFF 可以立即开始开发，无需等待后端实现。
• 契约变更通知：当契约发生变更时，通过 Webhook 或消息队列通知所有订阅方，确保变更透明可追溯。