接口契约设计标准化模版（分包交付核心）

接口契约文档 v1.0:
服务信息:

• 服务名: user-center
• 版本: v1
• Base URL: https://api.example.com/api/v1
• 认证: Bearer Token (OAuth2)
• 协议: REST (OpenAPI 3.1) + gRPC (可选)

端点清单:

详细契约 (OpenAPI 3.1 片段):

openapi: 3.1.0
info:
  title: User Center API
  version: 1.0.0
servers:
  - url: https://api.example.com/api/v1
paths:
  /auth/login:
    post:
      summary: 用户登录
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, deviceFingerprint]
              properties:
                email: { type: string, format: email, example: 'user@example.com' }
                password: { type: string, format: password, minLength: 8, example: 'Secr3tP@ss' }
                deviceFingerprint: { type: string, example: 'fp_abc123...' }
                rememberMe: { type: boolean, default: false }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    AuthResponse:
      type: object
      required: [accessToken, refreshToken, expiresIn, tokenType]
      properties:
        accessToken: { type: string, example: 'eyJhbGciOiJIUzI1NiIs...' }
        refreshToken: { type: string, example: 'eyJhbGciOiJIUzI1NiIs...' }
        expiresIn: { type: integer, example: 900 }
        tokenType: { type: string, enum: [Bearer], example: 'Bearer' }
        user: { $ref: '#/components/schemas/User' }
    User:
      type: object
      properties:
        id: { type: string, format: uuid }
        email: { type: string, format: email }
        name: { type: string }
        avatar: { type: string, nullable: true }
        roles: { type: array, items: { type: string } }
        createdAt: { type: string, format: date-time }
  responses:
    Unauthorized:
      description: 认证失败
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    RateLimited:
      description: 请求过于频繁
      headers:
        Retry-After: { schema: { type: integer } }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []

类型定义 (TypeScript):

// types/api.ts
export interface AuthResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  tokenType: 'Bearer';
  user: User;
}
export interface User {
  id: string;
  email: string;
  name: string;
| avatar: string | null; |
  roles: string[];
  createdAt: string;
}

Mock 服务 (MSW):

// mocks/handlers.ts
import { http, HttpResponse } from 'msw';
export const handlers = [
  http.post('/api/v1/auth/login', async ({ request }) => {
    const body = await request.json();
    if (body.email === 'test@example.com' && body.password === 'password123') {
      return HttpResponse.json({
        accessToken: 'mock-access-token',
        refreshToken: 'mock-refresh-token',
        expiresIn: 900,
        tokenType: 'Bearer',
        user: { id: '1', email: body.email, name: 'Test User', avatar: null, roles: ['user'], createdAt: new Date().toISOString() }
      });
    }
    return HttpResponse.json({ code: 'INVALID_CREDENTIALS', message: 'Invalid email or password' }, { status: 401 });
  }),
];

破坏性变更清单:

契约测试:

• Provider: npm run test:contract:provider (Schemathesis)
• Consumer: npm run test:contract:consumer (Pact)