Vite 项目的 GraphQL 数据层：Apollo、urql、codegen 与缓存失效实战

实体复用多、订阅多、团队大  → Apollo Client
体积敏感、想自己控制链路    → urql
已有 TanStack 生态、按 key 缓存即可 → TanStack Query

npm i @apollo/client graphql graphql-ws
npm i -D @graphql-codegen/cli @graphql-codegen/client-preset

// src/lib/apollo.ts
import { ApolloClient, InMemoryCache, HttpLink, split } from '@apollo/client'
import { GraphQLWsLink } from '@apollo/client/link/subscriptions'
import { getMainDefinition } from '@apollo/client/utilities'
import { createClient } from 'graphql-ws'
const httpLink = new HttpLink({ uri: import.meta.env.VITE_GRAPHQL_ENDPOINT })
const wsLink = new GraphQLWsLink(createClient({
  url: import.meta.env.VITE_GRAPHQL_WS_ENDPOINT,
}))
const link = split(({ query }) => {
  const def = getMainDefinition(query)
  return def.kind === 'OperationDefinition' && def.operation === 'subscription'
}, wsLink, httpLink)
export const client = new ApolloClient({ link, cache: new InMemoryCache() })

// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'
const config: CodegenConfig = {
  schema: 'https://api.example.com/graphql',
  documents: ['src/**/*.{ts,tsx}'],
  generates: { './src/gql/': { preset: 'client' } },
}
export default config

import { graphql } from '@/gql'
import { useQuery } from '@apollo/client'
const UserQuery = graphql(`
  query UserDetail($id: ID!) {
    user(id: $id) { id name }
  }
`)
export function useUser(id: string) {
  const { data, loading, error } = useQuery(UserQuery, { variables: { id } })
  return { user: data?.user, loading, error }
}

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/graphql': {
        target: 'http://localhost:4000',
        changeOrigin: true,
        ws: true, // 同时代理订阅的 WebSocket
      },
    },
  },
})

// src/mocks/handlers.ts
import { graphql, HttpResponse } from 'msw'
export const handlers = [
  graphql.query('UserDetail', ({ variables }) =>
    HttpResponse.json({ data: { user: { id: variables.id } } })),
]

// src/features/user/useUsers.ts
import { graphql } from '@/gql'
import { useQuery } from '@apollo/client'
const UsersQuery = graphql(`
  query Users($page: Int!) {
    users(page: $page) { id name }
  }
`)
export function useUsers(page = 1) {
  return useQuery(UsersQuery, { variables: { page } })
}

const [createUser] = useMutation(CreateUserMutation, {
  optimisticResponse: ({ name }) => ({
    createUser: { __typename: 'User', id: 'temp', name },
  }),
  update(cache, { data }) {
    cache.modify({ fields: { users: () => data!.createUser } })
  },
})

列表页 User:1 ─┐
              ├─→ 缓存里的同一条记录 → 改一处，两处都刷新
详情页 User:1 ─┘

await createUser({ variables: { name }, refetchQueries: ['Users'] })

// key 结构：['users', { page }]
queryClient.invalidateQueries({ queryKey: ['users'] }) // 失效所有分页

归一化（Apollo / urql） → 按实体 id 同步，缓存是「表」
key 化（TanStack Query）→ 按 query key 同步，缓存是「映射」

useSubscription(MESSAGE_ADDED, {
  onData: ({ client, data }) => {
    const msg = data.data?.messageAdded
    if (!msg) return
    client.cache.updateQuery({ query: MessagesQuery }, (prev) =>
      prev ? { messages: [...prev.messages, msg] } : prev,
    )
  },
})

createClient({
  url: import.meta.env.VITE_GRAPHQL_WS_ENDPOINT,
  retryAttempts: 10,
  shouldRetry: () => true,
})

const UserDetail = lazy(() => import('./features/user/UserDetail'))

✅ 查询文档写在被 lazy 引入的模块内 → 文档进该 chunk
❌ 所有查询集中在一个 graphql.ts 且被入口引用 → 文档全进主包

npx vite build
ls -la dist/assets/*.js | head         # 看 chunk 数量与体积
grep -l "query Users" dist/assets/*.js # 确认文档落在预期 chunk

npx graphql-codegen --config codegen.ts --check

# .github/workflows/graphql.yml
name: graphql-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
      - run: npx graphql-codegen --config codegen.ts --check

□ 端点走 import.meta.env.VITE_GRAPHQL_* 而非硬编码
□ 订阅与查询用 split 分流，代理开启 ws: true
□ 实体类型带 id，启用归一化缓存
□ codegen 产物已提交，CI 跑 --check，Mock 用 DEV 包住动态导入
□ 变更后明确失效策略，订阅配断线重连与退避

契约靠 codegen（类型即文档）
缓存靠归一化（id 即同步）
实时靠订阅（ws 即通道）
回归靠 CI（check 即门禁）