4. 接口契约基础：OpenAPI/Swagger规范、gRPC Protobuf契约、契约优先（Contract-First）开发模式

在数据库迁移领域建模驱动接口设计中，接口契约是连接领域模型与分布式系统的桥梁。本章聚焦三种核心契约技术：OpenAPI/Swagger、gRPC Protobuf，以及契约优先开发模式。理解这些契约的语法、语义和版本控制策略，是确保数据库迁移过程中上下游系统稳定协作的前提。

4.1 OpenAPI / Swagger 规范

OpenAPI 规范（原 Swagger 规范）是目前最流行的 RESTful API 契约标准。它使用 JSON 或 YAML 格式描述 API 的端点、请求/响应结构、参数、认证方式等。在数据库迁移场景中，OpenAPI 常用于定义数据查询、变更、同步等 HTTP 接口。

4.1.1 核心结构

4.1.2 数据库迁移场景示例

openapi: 3.0.3
info:
  title: 数据库迁移数据导出接口
  version: 1.2.0
  description: 用于从源数据库导出增量变更数据
paths:
  /export/changes:
    get:
      summary: 获取增量变更记录
      parameters:
        - name: since_version
          in: query
          required: true
          schema:
            type: integer
        - name: batch_size
          in: query
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: 成功返回变更记录列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChangeRecord'
components:
  schemas:
    ChangeRecord:
      type: object
      properties:
        change_id:
          type: string
        table_name:
          type: string
        operation:
          type: string
          enum: [INSERT, UPDATE, DELETE]
        row_data:
          type: object
        version:
          type: integer

4.2 gRPC Protobuf 契约

gRPC 使用 Protocol Buffers（Protobuf）作为接口定义语言（IDL），适用于高性能、低延迟的数据库迁移场景，尤其是跨服务的数据同步和流式传输。Protobuf 契约以 .proto 文件形式存在，定义服务接口和消息结构。

4.2.1 Protobuf 核心语法

syntax = "proto3";

package datamigration.v1;

// 定义数据迁移服务
service DataMigrationService {
  // 单向导出
  rpc ExportChanges(ExportRequest) returns (ExportResponse);
  // 服务端流式导出（适合大数据量）
  rpc StreamExportChanges(ExportRequest) returns (stream ChangeRecord);
}

// 导出请求消息
message ExportRequest {
  int64 since_version = 1;
  int32 batch_size = 2;
  string source_schema = 3;
}

// 变更记录消息
message ChangeRecord {
  string change_id = 1;
  string table_name = 2;
  string operation = 3;  // INSERT / UPDATE / DELETE
  bytes row_data = 4;    // 序列化的行数据
  int64 version = 5;
}

// 导出响应消息
message ExportResponse {
  repeated ChangeRecord records = 1;
  int64 next_version = 2;
  bool has_more = 3;
}

4.2.2 OpenAPI 与 gRPC Protobuf 对比

4.3 契约优先（Contract-First）开发模式

契约优先开发模式强调先定义接口契约，再实现服务端和客户端代码。在数据库迁移领域建模中，这种模式能有效避免“实现漂移”——即数据库 schema 变更后，API 接口与数据模型不一致的问题。

4.3.1 契约优先工作流

1. 领域建模：基于数据库迁移需求，识别实体、值对象、聚合根。
2. 契约定义：使用 OpenAPI 或 Protobuf 编写接口契约，包含所有端点、消息结构、错误码。
3. 契约评审：团队（后端、前端、DBA）共同评审契约，确保覆盖所有迁移场景。
4. 契约版本化：将契约文件纳入 Git 仓库，与数据库迁移脚本版本对齐。
5. 代码生成：使用工具（如 openapi-generator、protoc）生成服务端骨架和客户端 SDK。
6. 实现与测试：基于生成的骨架编写业务逻辑，使用契约作为测试断言依据。

4.3.2 契约优先 vs 代码优先

4.4 契约版本控制策略

接口契约的版本控制直接决定数据库迁移过程中上下游系统的兼容性。以下是三种主流策略：

• URL 路径版本：/api/v1/users → /api/v2/users。适合 OpenAPI，变更明显但 URL 会膨胀。
• 请求头版本：Accept: application/vnd.migration.v2+json。适合 RESTful 风格，URL 保持简洁。
• Protobuf package 版本：package datamigration.v1; → package datamigration.v2;。gRPC 原生支持，服务名可共存。