API契约与版本治理：OpenAPI/Protobuf契约管理、兼容性检查与SDK自动生成

# api/openapi.yaml
openapi: 3.0.3
info:
  title: Payment API
  version: 1.4.0
paths:
  /v1/payments/{payment_id}:
    get:
      operationId: getPayment
      parameters:
        - name: payment_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'

# 生成 Go 服务骨架
oapi-codegen -package api -generate types,chi-server,spec api/openapi.yaml > gen/api/api.gen.go

api-contracts/
├── openapi/
│   ├── openapi.yaml            # 聚合入口（root document）
│   └── components/
│       ├── schemas/
│       │   ├── user.yaml
│       │   └── payment.yaml
│       └── parameters/
├── proto/
│   ├── buf.yaml
│   └── user/v1/user.proto
├── asyncapi/
│   └── order-events.yaml
└── OWNERS.md                   # 契约模块负责人

components:
  schemas:
    User:
      $ref: './components/schemas/user.yaml'

# 校验 OpenAPI 语法与 Schema 引用
npx @redocly/cli lint api/openapi.yaml
npx @redocly/cli bundle api/openapi.yaml --output dist/openapi.bundle.yaml

buf lint      # 静态检查（风格、命名、注释规范）
buf build     # 构建描述符集
buf breaking  # 兼容性检查（对基线）
buf generate  # 生成代码

# buf.yaml
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
    - COMMENTS
breaking:
  use:
    - FILE
deps:
  - buf.build/googleapis/googleapis

# 对比两个版本，找出破坏性差异
npx @openapi-contrib/openapi-diff dist/openapi.v1.yaml dist/openapi.v2.yaml

NewBreakingChanges:
- GET /v1/users: response 200 application/json schema missing required property 'id'
- POST /v1/payments: request body schema added required property 'amount'

# 以 git 主分支为基线，检查当前工作区是否破坏兼容
buf breaking --against 'git://main#branch=main,subdir=proto'

## 契约变更说明
- 受影响 API：/v1/users, UserService/GetUser
- 变更类型：新增字段 / 破坏性变更 / 文档修正
- 兼容性检查结果：⚠️ 破坏性（需走版本升级流程）
- 受影响消费者：web-app, partner-portal
- 迁移计划：双写、过渡期、Sunset 日期
- 关联 Issue：#1234

# .github/workflows/api-contract.yml
name: api-contract-governance
on:
  pull_request:
    paths:
      - 'api/**'
      - 'proto/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: OpenAPI lint
        run: npx @redocly/cli lint api/openapi.yaml
      - name: OpenAPI breaking change
        run: |
          npx @openapi-contrib/openapi-diff \
            dist/openapi.v1.yaml dist/openapi.bundle.yaml --fail-on-DiffHunks
      - name: Buf lint & breaking
        run: |
          cd proto
          buf lint
          buf breaking --against 'git://main#branch=main,subdir=proto'
      - name: Generate SDK & verify clean diff
        run: |
          make generate
          git diff --exit-code gen/   # 确保生成产物与契约同步提交

npx openapi-typescript api/openapi.yaml -o packages/sdk/src/schema.d.ts
npx openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o packages/sdk/src/gen

npm publish packages/sdk --registry https://npm.example.com

消费者：写 Pact 文件（期望） → 契约仓库 → 提供方：CI 中回放验证

// 消费者侧：写契约
const { Pact } = require('@pact-foundation/pact');
const provider = new Pact({
  consumer: 'web-app',
  provider: 'user-service',
});

test('get user', async () => {
  await provider.addInteraction({
    state: 'user exists',
    uponReceiving: 'a request for user 123',
    withRequest: { method: 'GET', path: '/v1/users/123' },
    willRespondWith: {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
      body: { id: '123', name: 'Alice', email: 'alice@example.com' },
    },
  });
  // ...
  await provider.verify();
});

HTTP/1.1 200 OK
Sunset: Thu, 27 Sep 2027 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/migration-guide>; rel="sunset"