Apollo GraphQL Patterns

Patterns canoniques pour utiliser Apollo GraphQL côté serveur et client en 2026.

1. Apollo Server (Node.js)

npm install @apollo/server graphql @apollo/datasource-rest dataloader

// server.ts
import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { typeDefs } from './schema.js'
import { resolvers } from './resolvers.js'

const server = new ApolloServer({
  typeDefs,
  resolvers,
  csrfPrevention: true,
  introspection: process.env.NODE_ENV !== 'production',
  formatError: (formattedError, error) => {
    // Strip stack traces in production
    if (process.env.NODE_ENV === 'production') {
      return { message: formattedError.message, code: formattedError.extensions?.code }
    }
    return formattedError
  },
})

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({
    user: await authenticateUser(req.headers.authorization),
    loaders: createDataLoaders(),
  }),
  listen: { port: 4000 },
})

console.log(`🚀 Server ready at ${url}`)

2. Schema design

# schema.graphql
type Query {
  user(id: ID!): User
  users(first: Int = 10, after: String): UserConnection!
  search(query: String!, type: SearchType): SearchResult!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
}

type Subscription {
  userOnline(roomId: ID!): User!
}

# Relay-style cursor pagination
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Errors as data (union)
union CreateUserPayload = CreateUserSuccess | UserError

type CreateUserSuccess {
  user: User!
}

type UserError {
  message: String!
  field: String
  code: ErrorCode!
}

enum ErrorCode {
  INVALID_INPUT
  DUPLICATE
  NOT_FOUND
  UNAUTHORIZED
}

3. DataLoader (avoid N+1)

import DataLoader from 'dataloader'

export function createDataLoaders() {
  return {
    userById: new DataLoader<string, User>(async (ids) => {
      const users = await db.user.findMany({ where: { id: { in: [...ids] } } })
      const map = new Map(users.map(u => [u.id, u]))
      return ids.map(id => map.get(id) || new Error(`User ${id} not found`))
    }),
  }
}

// In resolver
const resolvers = {
  Post: {
    author: (post, _, { loaders }) => loaders.userById.load(post.authorId),
  },
}

Sans DataLoader, requêter 100 posts → 100 SELECT auteur. Avec DataLoader → 1 SELECT batched.

4. Apollo Client (React)

import { ApolloClient, InMemoryCache, ApolloProvider, gql } from '@apollo/client'

const client = new ApolloClient({
  uri: 'https://api.example.com/graphql',
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          users: {
            // Pagination merge
            keyArgs: false,
            merge(existing, incoming) {
              return {
                ...incoming,
                edges: [...(existing?.edges ?? []), ...incoming.edges],
              }
            },
          },
        },
      },
    },
  }),
  headers: {
    authorization: `Bearer ${token}`,
  },
})

function App() {
  return (
    <ApolloProvider client={client}>
      <UsersList />
    </ApolloProvider>
  )
}

const GET_USERS = gql`
  query GetUsers($first: Int!, $after: String) {
    users(first: $first, after: $after) {
      edges {
        node { id name email }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
`

function UsersList() {
  const { data, loading, fetchMore } = useQuery(GET_USERS, { variables: { first: 20 } })
  // ...
}

5. Federation v2 (microservices)

# Subgraph: users
extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable"])

type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
}

# Subgraph: posts
extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key"])

type Post @key(fields: "id") {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type User @key(fields: "id") {
  id: ID! @external
  posts: [Post!]!
}

# Compose supergraph
rover supergraph compose --config supergraph.yaml > supergraph.graphql

# Run Apollo Router (Rust)
./router --supergraph supergraph.graphql

6. Security

import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled'
import depthLimit from 'graphql-depth-limit'
import { createComplexityRule } from 'graphql-validation-complexity'

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    depthLimit(7),  // max query depth
    createComplexityRule({ maximumComplexity: 1000 }),
  ],
  plugins: [
    process.env.NODE_ENV === 'production'
      ? ApolloServerPluginLandingPageDisabled()
      : ApolloServerPluginLandingPageGraphQLPlayground(),
  ],
  csrfPrevention: true,  // require Apollo-Require-Preflight header
})

Persisted queries : ne permettre que les queries pré-approuvées en prod (anti-DDoS).

# Generate persisted query manifest
npx generate-persisted-query-manifest

7. Codegen

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

npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node
graphql-codegen

Résultat : types TypeScript auto-générés depuis le schema → end-to-end type safety.

8. Anti-patterns

1. N+1 queries sans DataLoader — kills perf
2. Resolvers qui font appel direct DB au lieu de data sources
3. Pas de depth limit — query récursive infinie possible
4. Pas de complexity rule — query coûteuse en compute
5. Introspection activée en prod — schema exposé aux attaquants
6. Errors via Error throws au lieu d'union types — UX cliente médiocre
7. Pagination offset-based au lieu de cursor — incohérent sur grosse data
8. @apollo/client v3 sans normalized cache config — re-fetches inutiles
9. Pas de persisted queries en prod — DDoS facile
10. Schema-first ET code-first mélangés — confusion équipe
11. Federation sans router Apollo Router — Apollo Gateway legacy slow
12. Pas de codegen TS — types out-of-sync

Checklist

• Apollo Server 4+ (v3 EOL)
• DataLoader sur toutes les relations
• Depth limit + complexity rule
• Errors as data (union types)
• Cursor-based pagination (Relay style)
• Persisted queries en prod
• CSRF prevention activé
• Introspection désactivée en prod
• Codegen TypeScript en CI
• Federation via Apollo Router (pas Gateway)
• Schema registry Apollo Studio
• Tests integration avec @apollo/server-integration-testing

Quand déléguer

• API design haut niveau → agent api-designer (ce plugin)
• gRPC → skill grpc-patterns (à créer si besoin)
• REST classique → skill api-design (ce plugin)
• Frontend React/Vue/Angular → skills frontend (atum-stack-web)

Ressources

• https://www.apollographql.com/docs/apollo-server/
• https://www.apollographql.com/docs/react/
• https://www.apollographql.com/docs/federation/
• https://github.com/apollographql/skills (source inspiration officielle)