GraphQL 代码生成与端到端类型安全：graphql-codegen 实战

// ❌ 手写类型：与 Schema 无关联，改字段不会报错
interface User {
  id: string;
  name: string;      // Schema 里可能已经改成了 fullName
  avatarUrl?: string;
}

// 查询返回的其实是 { id, fullName, avatar { url } }
const { data } = useQuery(gql`
  query GetUser { user { id fullName avatar { url } } }
`);
console.log(data.user.name); // undefined，运行时才炸

# 一次生成，处处受用
npm i -D @graphql-codegen/cli \
         @graphql-codegen/typescript \
         @graphql-codegen/typescript-operations \
         @graphql-codegen/typed-document-node

# codegen.ts 或 codegen.yml
schema: './schema.graphql'          # 或 http://localhost:4000/graphql
documents: 'src/**/*.{graphql,tsx,ts}'
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript                   # 生成 Schema 基础类型
      - typescript-operations        # 生成查询/变更的类型
      - typed-document-node          # 生成类型化 DocumentNode
    config:
      scalars:
        DateTime: string
        JSON: unknown
      avoidOptionals: true
      dedupeFragments: true

# 一次性生成
npx graphql-codegen --config codegen.ts

# 监听模式（开发时）
npx graphql-codegen --config codegen.ts --watch

# 在 package.json 中固定脚本
# "codegen": "graphql-codegen --config codegen.ts"

// 输入：src/queries/GetUser.graphql
// query GetUser($id: ID!) {
//   user(id: $id) { id fullName avatar { url } }
// }

// 输出：src/generated/graphql.ts
import { TypedDocumentNode } from '@graphql-typed-document-node/core';

export const GetUserDocument = {
  kind: 'Document',
  // ...
} as unknown as TypedDocumentNode<GetUserQuery, GetUserQueryVariables>;

export type GetUserQuery = {
  user: {
    id: string;
    fullName: string;
    avatar: { url: string } | null;
  } | null;
};

export type GetUserQueryVariables = { id: string };

import { useQuery } from '@apollo/client';
import { GetUserDocument } from '../generated/graphql';

function Profile({ id }: { id: string }) {
  // data 的类型自动推断为 GetUserQuery | undefined
  const { data, loading } = useQuery(GetUserDocument, {
    variables: { id },      // ✅ 缺少或类型错误会立即报错
  });

  if (loading) return <Spinner />;
  // data.user.fullName 全程有类型提示
  return <h1>{data?.user?.fullName}</h1>;
}

// 变量错误：id 应为 string，传 number 报错
useQuery(GetUserDocument, { variables: { id: 123 } });
//                                   ~~~~~~~~ Type 'number' is not assignable to 'string'

// 响应字段错误：Schema 中没有 email
const email = data?.user?.email;
//                       ~~~~~ Property 'email' does not exist

# src/components/UserCard.fragment.graphql
fragment UserCard on User {
  id
  fullName
  avatar { url }
}

// codegen 生成 UserCardFragment 类型
import { UserCardFragment } from '../generated/graphql';

export function UserCard({ user }: { user: UserCardFragment }) {
  // user 只包含 fragment 声明的字段，组件依赖被显式化
  return (
    <div>
      <img src={user.avatar?.url} alt={user.fullName} />
      <span>{user.fullName}</span>
    </div>
  );
}

# 父查询只关心"谁"，不关心"长什么样"
query UserList {
  users {
    id
    ...UserCard
  }
}

# codegen.ts —— 单配置多输出
generates:
  # Web：Apollo Client
  apps/web/src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node
    documents: 'apps/web/src/**/*.graphql'

  # React Native：同插件、不同 scalars
  apps/mobile/src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node
    documents: 'apps/mobile/src/**/*.graphql'
    config:
      scalars:
        DateTime: string   # RN 不用 Date 对象

  # Node 服务端：生成 resolver 类型
  apps/api/src/generated/resolvers.ts:
    plugins:
      - typescript
      - typescript-resolvers
    config:
      contextType: '../context#Context'
      mappers:
        User: '../models#UserModel'

// ✅ 生成类型：网络层数据结构
import type { GetUserQuery } from '../generated/graphql';

// ✅ 手写类型：领域模型（可能与网络结构不同）
interface UserProfile {
  displayName: string;
  joinedAt: Date;
}

// 显式映射：把网络类型转换为领域类型
function toProfile(raw: GetUserQuery['user']): UserProfile | null {
  if (!raw) return null;
  return {
    displayName: raw.fullName,
    joinedAt: new Date(raw.createdAt),  // 标量 string → Date
  };
}

// 用 unknown 强制显式收窄，避免 any 渗透
const meta = data.node.metadata as unknown;
if (isOrderMeta(meta)) {
  console.log(meta.trackingNo);
}

// 联合类型查询生成判别联合
type SearchResult =
  | { __typename: 'User'; id: string; fullName: string }
  | { __typename: 'Order'; id: string; total: number };

// switch 收窄，exhaustive check 保证不漏分支
function render(r: SearchResult) {
  switch (r.__typename) {
    case 'User': return r.fullName;
    case 'Order': return `¥${r.total}`;
    default: {
      const _exhaustive: never = r;
      return _exhaustive;
    }
  }
}

# .github/workflows/codegen-check.yml
name: Codegen Check
on: [pull_request]

jobs:
  codegen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci

      - name: Regenerate types
        run: npm run codegen

      - name: Fail if generated files drifted
        run: |
          if ! git diff --quiet; then
            echo "::error::Generated types are out of date. Run 'npm run codegen'."
            git diff --stat
            exit 1
          fi

# lefthook / husky 中在提交前自动生成
npx lefthook add pre-commit
# lefthook.yml
# pre-commit:
#   commands:
#     codegen:
#       glob: "**/*.graphql"
#       run: npm run codegen && git add src/generated

# .gitattributes —— 让生成文件在 diff 中折叠
src/generated/* linguist-generated=true

/* eslint-disable */
// @generated by graphql-codegen — DO NOT EDIT
// 手动修改将在下次生成时丢失