API 类型生成与契约：tRPC、OpenAPI Codegen 与 GraphQL Codegen

tRPC          ：Code 优先，前后端 TS 同库 → 类型零成本共享
OpenAPI Codegen：Schema 优先，规范文件 → 生成 TS 类型/客户端
GraphQL Codegen ：Schema 优先，.graphql 文件 → 生成 TS 类型

前后端都是 TS 且耦合紧密 → tRPC（零成本、类型实时）
多语言/对外 API/需要文档 → OpenAPI（规范即文档）
查询灵活性高/聚合多源   → GraphQL

前后端共享「过程（procedure）定义」——类型自动推断，无 codegen
后端定义 router → 前端 import 类型 → 调用自动带类型

// server/router.ts
import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()

const appRouter = t.router({
  getUser: t.procedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      // 返回类型由实现推断
      return { id: input.id, name: 'Alice', role: 'user' }
    }),
  updateUser: t.procedure
    .input(z.object({ id: z.string(), name: z.string() }))
    .mutation(async ({ input }) => {
      // ... 更新
      return { success: true }
    }),
})

export type AppRouter = typeof appRouter

// client/App.tsx
import { createTRPCProxyClient } from '@trpc/client'
import type { AppRouter } from '../server/router'   // 只 import 类型

const trpc = createTRPCProxyClient<AppRouter>({ links: [...] })

const user = await trpc.getUser.query({ id: '1' })   // user: { id, name, role }
user.role.toUpperCase()   // ✅ 类型正确
// trpc.getUser.query({ id: 1 })  ❌ input 类型错误（id 应为 string）

优点：零 codegen、类型实时同步、input 有 zod 运行时验证
代价：前后端必须 TS 同库（或共享类型包）、对「对外 REST API」不友好

OpenAPI（Swagger）规范：用 YAML/JSON 描述 HTTP API
  → 路径、方法、请求/响应 Schema
  → 一份规范 = API 文档 + 代码生成器输入

# openapi.yaml（片段）
openapi: 3.0.0
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }

# 方式一：openapi-typescript（生成纯类型）
npx openapi-typescript openapi.yaml -o api-schema.ts

# 方式二：swagger-typescript-api（生成客户端 + 类型）
npx swagger-typescript-api -p openapi.yaml -o src/api -n client.ts

// api-schema.ts（openapi-typescript 生成）
export interface paths {
  '/users/{id}': {
    get: {
      parameters: { path: { id: string } }
      responses: { 200: { content: { 'application/json': components['schemas']['User'] } } }
    }
  }
}
export interface components {
  schemas: {
    User: { id: string; name: string }
  }
}

import type { paths, components } from './api-schema'

type User = components['schemas']['User']   // { id: string; name: string }

// 类型化 fetch
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`)
  if (!res.ok) throw new Error('bad')
  return res.json() as User
}

# 后端变更 OpenAPI → 重新生成前端类型 → 类型检查
steps:
  - run: npx openapi-typescript ../../api/openapi.yaml -o src/api/schema.ts
  - run: pnpm typecheck   # 类型不匹配 → CI 失败

1. 响应类型只是「声明」，运行时仍要校验（加 zod）
2. OpenAPI 的 $ref/oneOf 会映射成复杂 TS 联合
3. 生成文件要提交进仓库（避免每次构建都生成）
4. 严格模式：nullable/optional 语义要对齐 tsconfig

# schema.graphql
type User { id: ID! name: String! posts: [Post!]! }
type Query { user(id: ID!): User }

# codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: './src/**/*.graphql',
  generates: {
    './src/gql/': { preset: 'client' }   // 生成 types + hooks
  }
}
export default config

// src/UserProfile.tsx
import { useUserQuery } from './gql/graphql'

function UserProfile({ id }: { id: string }) {
  const { data } = useUserQuery({ variables: { id } })
  // data.user.name 类型精确；data.user.xxx 不存在则报错
  return <div>{data?.user?.name}</div>
}

优点：精确到「每个查询所需字段」的类型（字段级类型安全）
代价：需要 GraphQL 后端；文档与 codegen 配置有学习成本

方案一（tRPC）：前后端同库 import router 类型 → 零共享成本
方案二（类型包）：@repo/types 放 DTO → 两端 import
方案三（生成）：契约文件 → 两端各自生成（OpenAPI/GraphQL）

推荐混合：
  对外 REST API → OpenAPI Codegen（契约解耦 + 文档）
  内部全栈功能 → tRPC（零成本实时）
  复杂查询     → GraphQL Codegen
按「耦合度 + 对外需求」分段选型，不强制统一

1. 生成文件提交入库，CI 中「重新生成 + typecheck」防漂移
2. 运行时验证（zod）与生成类型并存：生成声明、zod 校验
3. 契约变更走 PR 评审，前端类型不匹配即阻断
4. 版本策略：破坏性变更进大版本

二者互补而非替代：
  类型生成：让「类型声明的修改」在编译期被发现
  zod     ：让「运行时拿到的数据」被验证，非法即抛错
最佳实践：生成类型 + zod Schema 各管一层

加字段：向后兼容（旧前端忽略新字段）
改字段类型/删除字段：破坏性变更
重命名：破坏性变更

演进规则：
  1. 加字段优先（兼容）
  2. 破坏性变更用「新增端点/版本」
  3. 字段废弃用 deprecated 标记（OpenAPI/GraphQL 都支持）

URL 版本：/api/v1/users、/api/v2/users（常见）
Header 版本：Accept: application/vnd.app.v2+json
GraphQL：无 URL 版本，靠 Schema 演进 + 字段 deprecated

前端策略：按版本生成类型 → 逐步迁移，老版本类型保留

对外网关 REST → OpenAPI 规范 → 生成 SDK 给外部/多语言
内部服务间     → tRPC（同 TS）→ 类型实时
前端复杂查询   → GraphQL → Codegen hooks
共享 DTO 放 @repo/types → 三处统一引用