docs(10_Wiki): Topic_Business/General/Graphic/Programming을 Topics/ 하위로 이동

최상위 10_Wiki/Topic_*였던 4개 카테고리 폴더를 10_Wiki/Topics/Topic_* 로 재배치. 콘텐츠 변경 없음(순수 폴더 이동) — Topics/ 하위 나머지 폴더는 이미 지난 커밋에서 전부 정리된 상태(잔존 항목은 에이전트 운영 상태 및 사용자가 보존을 요청한 업데이트0615/무제 3.canvas 뿐).
2026-07-05 00:44:01 +09:00
parent e9cbf23ab5
commit 9a135bd19d
6127 changed files with 0 additions and 0 deletions
@@ -0,0 +1,177 @@
+---
+id: wiki-2026-0508-codegen
+title: Codegen (GraphQL, OpenAPI, Schema-driven)
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Code Generation, GraphQL Codegen, OpenAPI Codegen]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [codegen, graphql, openapi, typescript, tooling]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: TypeScript
+  framework: GraphQL Code Generator / openapi-typescript
+---
+
+# Codegen (Schema-driven Code Generation)
+
+## 매 한 줄
+> **"매 schema 가 single source of truth"**. Codegen 은 GraphQL/OpenAPI/Protobuf schema 에서 type 과 client code 를 자동 생성 — 매 manual sync 의 X, drift 의 zero, refactor 매 compile-time safe.
+
+## 매 핵심
+
+### 매 주요 도구 (2026)
+- **GraphQL**: `@graphql-codegen/cli` (client preset), `gql.tada` (zero-config inline).
+- **OpenAPI**: `openapi-typescript` (types), `openapi-fetch` (typed client), `orval` (React Query hooks).
+- **gRPC/Protobuf**: `bufbuild/protobuf-es`, `connect-es`.
+- **DB schema**: `kysely-codegen`, `drizzle-kit`, Prisma.
+
+### 매 출력 종류
+- Type definitions only (lightweight).
+- Typed client (operations + types).
+- Hooks/composables (React Query, SWR, urql).
+- Server stubs (resolvers, controllers).
+
+### 매 watch vs build-time
+- Dev: watch mode → 매 save 시 regen.
+- CI: `--check` 로 매 schema/code drift 검출.
+- Pre-commit: 매 generated files 매 staged 보장.
+
+## 💻 패턴
+
+### GraphQL client preset (@graphql-codegen/cli)
+```yaml
+# codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+  schema: 'https://api.example.com/graphql',
+  documents: ['src/**/*.{ts,tsx}'],
+  generates: {
+    'src/gql/': {
+      preset: 'client',
+      config: { useTypeImports: true, scalars: { DateTime: 'string' } },
+    },
+  },
+};
+export default config;
+```
+
+### Using generated `graphql()` (typed documents)
+```ts
+import { graphql } from '@/gql';
+import { useQuery } from '@tanstack/react-query';
+
+const FlightSearch = graphql(`
+  query FlightSearch($from: String!, $to: String!) {
+    flights(from: $from, to: $to) { id price airline }
+  }
+`);
+
+export function useFlights(vars: { from: string; to: string }) {
+  return useQuery({
+    queryKey: ['flights', vars],
+    queryFn: () => request('/graphql', FlightSearch, vars),
+  });
+}
+```
+
+### gql.tada (zero-config alternative)
+```ts
+import { graphql } from 'gql.tada';
+
+const Query = graphql(`
+  query Me { me { id email } }
+`);
+// 매 inferred 매 fully typed — no codegen step
+```
+
+### openapi-typescript + openapi-fetch
+```bash
+npx openapi-typescript ./openapi.yaml -o ./src/api/schema.ts
+```
+```ts
+import createClient from 'openapi-fetch';
+import type { paths } from './api/schema';
+
+const api = createClient<paths>({ baseUrl: 'https://api.example.com' });
+
+const { data, error } = await api.GET('/users/{id}', {
+  params: { path: { id: '42' } },
+});
+// data 매 매 fully typed
+```
+
+### orval — React Query hooks from OpenAPI
+```ts
+// orval.config.ts
+export default {
+  api: {
+    input: './openapi.yaml',
+    output: {
+      target: './src/api/generated.ts',
+      client: 'react-query',
+      mode: 'tags-split',
+    },
+  },
+};
+```
+
+### Drizzle Kit — DB schema introspection
+```bash
+drizzle-kit introspect:pg --connectionString=$DATABASE_URL --out=./src/db
+```
+
+### CI drift check
+```yaml
+# .github/workflows/codegen-check.yml
+- run: pnpm codegen
+- run: git diff --exit-code src/gql src/api
+```
+
+### Husky pre-commit
+```sh
+# .husky/pre-commit
+pnpm codegen && git add src/gql src/api
+```
+
+## 매 결정 기준
+| 상황 | 도구 |
+|---|---|
+| GraphQL + React/Vue | `@graphql-codegen` client preset |
+| GraphQL + want zero step | `gql.tada` |
+| OpenAPI types only | `openapi-typescript` |
+| OpenAPI + hooks | `orval` |
+| DB-first | Drizzle / Prisma / Kysely codegen |
+
+**기본값**: GraphQL → client preset; REST → `openapi-typescript` + `openapi-fetch`.
+
+## 🔗 Graph
+- 부모: [[Type-Safety]]
+- 변형: [[OpenAPI]] · [[gRPC]]
+- 응용: [[React-Query]]
+- Adjacent: [[Contract-Testing]]
+
+## 🤖 LLM 활용
+**언제**: schema-driven API integration / 매 type drift 매 painful 한 monorepo.
+**언제 X**: 매 throwaway prototype, schema 매 unstable.
+
+## ❌ 안티패턴
+- **Hand-writing GraphQL types**: 매 drift 의 zero-day issue.
+- **Committing nothing then expecting safety**: 매 generated files 매 commit + CI check 둘 다 필요.
+- **Running codegen only locally**: 매 CI drift check 의 X 면 PR 매 깨짐.
+
+## 🧪 검증 / 중복
+- Verified (the-guild.dev / openapi-ts.dev / orval.dev official docs).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — codegen tools (GraphQL/OpenAPI) with patterns |