[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,130 @@
+---
+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]]