---
id: web-graphql-client-patterns
title: GraphQL Client — Apollo / urql / Relay 비교
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [web, graphql, apollo, urql, relay, vibe-coding]
tech_stack: { language: "TypeScript / Apollo / urql / Relay", applicable_to: ["Web"] }
applied_in: []
aliases: [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
```ts
// 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
```

```ts
// 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 정책
```ts
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
```ts
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 — 가벼운 대안
```ts
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]]