# npm
npm install @apollo/client graphql
 
# pnpm
pnpm add @apollo/client graphql
 
# yarn
yarn add @apollo/client graphql

# Apollo Client 4.x 额外需要
npm install rxjs

import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client'
 
const client = new ApolloClient({
  // GraphQL 服务端地址
  link: new HttpLink({
    uri: 'https://api.example.com/graphql',
    // 可选：认证头
    headers: {
      authorization: `Bearer ${token}`,
    },
  }),
  // 规范化缓存
  cache: new InMemoryCache({
    typePolicies: {
      // 自定义类型策略
      Query: {
        fields: {
          // 自定义字段合并策略
        },
      },
    },
  }),
  // 开发模式下启用详细日志
  connectToDevTools: process.env.NODE_ENV === 'development',
})

import React from 'react'
import { ApolloProvider, useQuery, gql } from '@apollo/client/react'
import { client } from './apollo-client'
 
// GraphQL 查询定义
const GET_USERS = gql`
  query GetUsers {
    users {
      id
      name
      email
    }
  }
`
 
// 数据展示组件
function UserList() {
  const { data, loading, error, dataState } = useQuery(GET_USERS)
 
  if (loading) return <p>加载中...</p>
  if (error) return <p>错误: {error.message}</p>
 
  return (
    <ul>
      {data.users.map((user) => (
        <li key={user.id}>{user.name} - {user.email}</li>
      ))}
    </ul>
  )
}
 
// 应用入口——挂载 ApolloProvider
export default function App() {
  return (
    <ApolloProvider client={client}>
      <UserList />
    </ApolloProvider>
  )
}

npm install @apollo/client-integration-nextjs

// app/providers.tsx
import { ApolloClient } from '@apollo/client-integration-nextjs'
 
export default function Providers({ children }) {
  return (
    <ApolloClient>
      {children}
    </ApolloClient>
  )
}

import { InMemoryCache } from '@apollo/client'
 
const cache = new InMemoryCache({
  // 类型策略——定义如何识别和合并实体
  typePolicies: {
    Book: {
      // 主键字段（默认使用 id 或 _id）
      keyFields: ['isbn'],
      fields: {
        // 自定义字段读取/合并逻辑
        reviews: {
          keyArgs: false,
          merge(existing = [], incoming) {
            return [...existing, ...incoming]
          },
        },
      },
    },
    // 分页查询的合并策略
    Query: {
      fields: {
        books: {
          keyArgs: ['genre'],
          merge(existing, incoming, { args }) {
            // offset 分页
            const merged = existing ? existing.slice() : []
            const { offset = 0 } = args ?? {}
            for (let i = 0; i < incoming.length; ++i) {
              merged[offset + i] = incoming[i]
            }
            return merged
          },
        },
      },
    },
  },
})

import { from, HttpLink } from '@apollo/client'
import { setContext } from '@apollo/client/link/context'
import { onError } from '@apollo/client/link/error'
import { RetryLink } from '@apollo/client/link/retry'
 
// 认证链路
const authLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    authorization: `Bearer ${getToken()}`,
  },
}))
 
// 错误处理链路
const errorLink = onError(({ graphQLErrors, networkError }) => {
  if (graphQLErrors) {
    graphQLErrors.forEach(({ message, locations, path }) =>
      console.error(`[GraphQL error]: ${message}`)
    )
  }
  if (networkError) {
    console.error(`[Network error]: ${networkError}`)
  }
})
 
// 重试链路
const retryLink = new RetryLink({
  attempts: { max: 3 },
  delay: { initial: 300, max: 3000, jitter: true },
})
 
// HTTP 链路
const httpLink = new HttpLink({ uri: '/graphql' })
 
// 组合链路
const link = from([errorLink, authLink, retryLink, httpLink])

import { TypedDocumentNode, gql } from '@apollo/client'
 
// 配合 GraphQL Code Generator 自动生成类型
type GetUsersQuery = {
  __typename?: 'Query'
  users: Array<{
    __typename?: 'User'
    id: string
    name: string
    email: string
  }>
}
 
type GetUsersQueryVariables = {
  first?: number
  after?: string
}
 
const GET_USERS: TypedDocumentNode<GetUsersQuery, GetUsersQueryVariables> = gql`
  query GetUsers($first: Int, $after: String) {
    users(first: $first, after: $after) {
      id
      name
      email
    }
  }
`

const { data, dataState } = useQuery(GET_POSTS)
// dataState: 'empty' | 'partial' | 'streaming' | 'complete'

import { isApolloError } from '@apollo/client'
 
try {
  const { data } = await client.query({ query: GET_DATA })
} catch (err) {
  if (isApolloError(err)) {
    console.error('GraphQL errors:', err.graphQLErrors)
  }
}

npx @apollo/client-codemod-migrate-3-to-4 src

import { makeVar, useReactiveVar } from '@apollo/client'
 
// 创建响应式变量
const themeVar = makeVar<'light' | 'dark'>('light')
 
// 在组件中使用
function ThemeToggle() {
  const theme = useReactiveVar(themeVar)
  return <button onClick={() => themeVar(theme === 'light' ? 'dark' : 'light')}>
    当前主题: {theme}
  </button>
}

# 安装 GraphQL Code Generator + Apollo Client 插件
npm install -D @graphql-codegen/cli @graphql-codegen/typed-document-node @graphql-codegen/typescript-operations @graphql-codegen/typescript

# codegen.yml
schema: 'https://api.example.com/graphql'
documents: './src/graphql/**/*.ts'
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node

import { MockedProvider } from '@apollo/client/testing'
import { render, screen } from '@testing-library/react'
import { GET_USERS } from './UserList'
 
const mocks = [
  {
    request: {
      query: GET_USERS,
    },
    result: {
      data: {
        users: [
          { id: '1', name: 'Alice', email: '[email protected]', __typename: 'User' },
        ],
      },
    },
  },
]
 
test('renders user list', async () => {
  render(
    <MockedProvider mocks={mocks} addTypename={false}>
      <UserList />
    </MockedProvider>
  )
  // 等待异步数据加载
  expect(await screen.findByText('Alice')).toBeInTheDocument()
})

# 自动迁移工具
npx @apollo/client-codemod-migrate-3-to-4 src

// ✅ 自动生成，类型安全
import { GetUsersDocument } from './generated/graphql'
const { data } = useQuery(GetUsersDocument, { variables: { first: 10 } })
 
// ❌ 手动类型，容易不一致
const { data } = useQuery<UsersData>(gql`...`)

const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        // 无限滚动：按 offset 追加
        feed: {
          keyArgs: ['type'],
          merge(existing, incoming, { args }) {
            const merged = existing?.items ? [...existing.items] : []
            const offset = args?.offset ?? 0
            merged.splice(offset, incoming.length, ...incoming)
            return { ...existing, items: merged, totalCount: incoming.totalCount }
          },
        },
      },
    },
  },
})

const { data, dataState } = useQuery(GET_POSTS)
 
switch (dataState) {
  case 'empty':
    return <SkeletonList />
  case 'partial':
    return <PostList posts={data.posts} isRefreshing />
  case 'complete':
    return <PostList posts={data.posts} />
}

const link = from([
  errorLink,      // 错误处理和上报
  authLink,       // 认证头注入
  retryLink,      // 网络失败重试
  loggerLink,     // 开发模式日志
  httpLink,       // 实际 HTTP 请求
])

import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries'
import sha256 from 'crypto-hash/sha256'
 
const persistedQueryLink = createPersistedQueryLink({
  sha256: (document) => sha256(print(document)),
})