4. 接口契约定义：OpenAPI/Swagger规范、gRPC Proto文件、GraphQL Schema定义

在数据库迁移过程中，API 接口契约是连接前端应用与后端数据层的“协议层”。当数据库版本发生变更（如字段重命名、表拆分、数据类型调整）时，API 契约必须同步演进，否则将导致客户端解析失败或数据不一致。本章聚焦三种主流接口契约定义方式——OpenAPI/Swagger、gRPC Proto 与 GraphQL Schema，并阐述它们如何与数据库版本对齐。

4.1 三种契约范式的对比

4.2 OpenAPI / Swagger 规范：RESTful 契约对齐

OpenAPI 规范通过 components/schemas 定义数据模型，这些模型应直接映射到数据库表结构。当数据库字段变更时，需同步更新 Schema 定义并递增 API 版本。

4.2.1 数据库字段变更的契约映射规则

• 新增字段：在 Schema 中标记为 nullable: true 或设置 default 值，避免破坏现有客户端。
• 重命名字段：旧字段标记为 deprecated: true，新增字段使用新名称，并在描述中注明迁移周期。
• 删除字段：先废弃（deprecated），至少保留一个主版本周期后再移除。
• 数据类型变更：必须创建新的 API 版本（如 /v2/），旧版本继续维护直到客户端完成迁移。

openapi: 3.0.3
info:
  title: 用户服务 API
  version: 2.0.0
paths:
  /v2/users/{id}:
    get:
      summary: 获取用户详情（v2）
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserV2'
components:
  schemas:
    UserV1:
      type: object
      properties:
        user_id:
          type: integer
        full_name:
          type: string
        email:
          type: string
    UserV2:
      type: object
      properties:
        user_id:
          type: integer
        full_name:
          type: string
          deprecated: true
          description: 已废弃，请使用 display_name
        display_name:
          type: string
        email:
          type: string
        phone:
          type: string
          nullable: true

4.3 gRPC Proto 文件：强类型契约对齐

gRPC 使用 Protocol Buffers（Proto3）作为接口定义语言。其核心优势在于字段编号（field number）机制——一旦发布，字段编号不可复用，天然支持向前/向后兼容。

4.3.1 Proto 文件与数据库版本对齐策略

syntax = "proto3";
package user.service.v2;

import "google/protobuf/timestamp.proto";

// 对应数据库 user 表 v2 版本
message User {
  int32 user_id = 1;
  string full_name = 2 [deprecated = true];  // 废弃，保留编号
  string display_name = 3;                    // 新字段
  string email = 4;
  optional string phone = 5;                  // 新增可选字段
  google.protobuf.Timestamp created_at = 6;
}

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

message GetUserRequest {
  int32 user_id = 1;
}

4.4 GraphQL Schema 定义：灵活查询契约对齐

GraphQL 的 Schema 定义语言（SDL）通过类型系统和指令（directive）来管理版本演进。其优势在于客户端可按需查询，但数据库迁移时需要在 Resolver 层做额外的适配工作。

4.4.1 Schema 废弃与迁移指令

• @deprecated：标准指令，标记字段为废弃状态，并说明替代字段。
• @dbVersion：自定义指令，标注字段对应的数据库版本号，用于自动化校验。
• 接口联合（Union/Interface）：当数据库表结构发生重大变化时，通过接口类型返回不同版本的数据结构。

directive @dbVersion(version: String!) on FIELD_DEFINITION

type User {
  id: ID!
  fullName: String @deprecated(reason: "使用 displayName")
  displayName: String! @dbVersion(version: "2.0")
  email: String!
  phone: String @dbVersion(version: "2.1")
  createdAt: String!
}

type Query {
  user(id: ID!): User
}

4.4.2 Resolver 层的版本路由

在 GraphQL Resolver 中，需要根据客户端请求的字段集合，动态决定从哪个数据库版本的表或视图中读取数据。以下是一个简化的版本路由逻辑：

const resolvers = {
  User: {
    displayName: (parent) => {
      // 如果客户端请求了 displayName，从 v2 表读取
      return db.query('SELECT display_name FROM users_v2 WHERE id = $1', [parent.id]);
    },
    fullName: (parent) => {
      // 如果客户端请求了已废弃的 fullName，从 v1 表读取（兼容旧客户端）
      return db.query('SELECT full_name FROM users_v1 WHERE id = $1', [parent.id]);
    }
  }
};

4.5 契约对齐的自动化校验流程

下图展示了从数据库 Schema 变更到 API 契约更新的自动化校验流水线：

4.6 契约对齐检查清单

• OpenAPI：检查 deprecated 标记是否与数据库废弃列同步；确认新增字段为 nullable 或包含默认值。
• gRPC Proto：验证所有已删除字段编号已加入 reserved 列表；确认新增字段编号未与历史编号冲突。
• GraphQL Schema：确保废弃字段的 @deprecated 原因中指明了替代字段；检查 Resolver 中是否实现了双版本数据源路由。
• 自动化门禁：在 CI 流水线中加入契约与数据库 Schema 的差异对比步骤，差异超过阈值（如字段不匹配率 > 5%）则阻断发布。