2nd/10_Wiki/Topics/Coding/Web_GraphQL_Client_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
web-graphql-client-patterns	GraphQL Client — Apollo / urql / Relay 비교	Coding	draft	B	conceptual	2026-05-09	2026-05-09	web graphql apollo urql relay vibe-coding	language applicable_to TypeScript / Apollo / urql / Relay Web		normalized cache query mutation subscription codegen

GraphQL Client

3대 클라이언트 — Apollo (가장 널리), urql (가벼움), Relay (Meta, 강력하지만 학습곡선). 공통: codegen 으로 타입 자동 + cache 정책 명시 + fragment co-location.

📖 핵심 개념

• Codegen: schema → TS 타입 + hook 자동.
• Normalized cache: id 기반 객체 dedup.
• Fragment: 컴포넌트가 자기 데이터 spec.

💻 코드 패턴

Apollo Client + codegen

// schema.graphql + queries.graphql 작성 후
// codegen.yml
schema: 'schema.graphql'
documents: 'src/**/*.graphql'
generates:
  src/__generated__/types.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

// query.graphql
query GetUser($id: ID!) {
  user(id: $id) { id email name }
}

// 사용
import { useGetUserQuery } from './__generated__/types';
function Profile({ id }: { id: string }) {
  const { data, loading, error } = useGetUserQuery({ variables: { id } });
  if (loading) return <Spinner />;
  if (error) return <Error msg={error.message} />;
  return <h1>{data?.user.name}</h1>;
}

Cache 정책

const client = new ApolloClient({
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          orders: { merge(existing = [], incoming) { return [...existing, ...incoming]; } }, // pagination
        },
      },
      Order: {
        keyFields: ['id'],
        fields: { items: { merge: false } }, // 항상 replace
      },
    },
  }),
});

Mutation + cache update

const [createPost] = useCreatePostMutation({
  update(cache, { data }) {
    cache.modify({
      fields: {
        posts(existing = []) {
          return [...existing, cache.writeFragment({
            data: data?.createPost,
            fragment: gql`fragment NewPost on Post { id title }`,
          })];
        },
      },
    });
  },
});

urql — 가벼운 대안

import { useQuery } from 'urql';

const [{ data, fetching, error }] = useQuery({
  query: GetUserDocument,
  variables: { id },
});

🤔 의사결정 기준

상황	클라이언트
큰 앱 + 복잡 cache	Apollo
가벼운 / Vue / Svelte	urql
Meta 스타일 fragment co-location 강제	Relay
Server Components / RSC	graphql-request 또는 fetch
Subscription 많이	apollo-client + ws link
단순 fetch	tanstack-query + graphql-request

❌ 안티패턴

• codegen 안 쓰고 string query: 타입 안전 0.
• fragment 안 쓰고 컴포넌트마다 큰 query: over-fetch + 중복.
• cache 정책 미정의 → list mutation 후 stale: cache.modify / refetchQueries.
• subscription 무한 reconnect 없음: 연결 끊겨도 모름.
• 모든 GraphQL 호출 서버 SSR: client 만 가능한 건 nullable.
• N+1 쿼리 그대로 노출: server 측 DataLoader 필수.

🤖 LLM 활용 힌트

• 신규 = Apollo + codegen + fragment.
• cache 정책은 도메인별 명시.

🔗 관련 문서

• DB_N_Plus_One
• React_Suspense_for_Data