前端接口契约驱动实践：基于 OpenAPI 自动化生成类型、SDK 与 Mock 服务

[后端导出 / 设计输出] 
       ↓ 
 OpenAPI 规范文件 (schema.json / schema.yaml)
       ↓
 ┌─────────────────┬─────────────────┐
 ↓                 ↓                 ↓
TS 类型定义        请求 SDK           本地 Mock 服务
(types.ts)       (api.ts)          (Prism / MSW)

openapi: 3.0.0
info:
  title: 用户服务 API
  version: 1.0.0
paths:
  /api/v1/users/{id}:
    get:
      summary: 获取指定用户信息
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 1001
        name:
          type: string
          example: "一步梅"
        email:
          type: string
          format: email
          example: "yibumei@example.com"
        role:
          type: string
          enum: [admin, editor, viewer]
          default: viewer

npm install -D openapi-typescript

{
  "scripts": {
    "gen:types": "openapi-typescript ./openapi.yaml -o ./src/api/schema.d.ts"
  }
}

export interface paths {
  "/api/v1/users/{id}": {
    get: operations["getUserById"];
  };
}

export interface components {
  schemas: {
    User: {
      id: number;
      name: string;
      email: string;
      role?: "admin" | "editor" | "viewer";
    };
  };
}

export interface operations {
  getUserById: {
    parameters: {
      path: {
        id: number;
      };
    };
    responses: {
      200: {
        content: {
          "application/json": components["schemas"]["User"];
        };
      };
    };
  };
}

npm install openapi-fetch

import createClient from "openapi-fetch";
import type { paths } from "./schema";

export const apiClient = createClient<paths>({ 
  baseUrl: "https://api.example.com" 
});

import { apiClient } from "./api/client";

async function fetchUserInfo(userId: number) {
  // 1. 输入 "/api/v1/users/{id}" 时会有 IDE 自动补全
  // 2. 如果缺少 params.path.id，TypeScript 会直接报错
  const { data, error } = await apiClient.GET("/api/v1/users/{id}", {
    params: {
      path: { id: userId },
    },
  });

  if (error) {
    console.error("请求失败", error);
    return;
  }

  // 3. 此时 data 会被自动推导为 components['schemas']['User']
  console.log(`用户姓名: ${data.name}, 角色: ${data.role}`);
}

npm install -D @stoplight/prism-cli

{
  "scripts": {
    "mock": "prism mock ./openapi.yaml -p 4010"
  }
}

[CLI] …  INFO  Using OpenAPI 3.0.0 specification
[CLI] ✔  info      Serving 1 path on http://127.0.0.1:4010
[CLI] ℹ  info      GET  http://127.0.0.1:4010/api/v1/users/1001

curl http://127.0.0.1:4010/api/v1/users/1001

{
  "id": 1001,
  "name": "一步梅",
  "email": "yibumei@example.com",
  "role": "viewer"
}