[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,146 @@
+---
+id: web-fetch-wrapper-design
+title: Fetch Wrapper 설계 — 인증 / 재시도 / 에러 정규화
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [web, fetch, http-client, vibe-coding]
+tech_stack: { language: "TypeScript / fetch", applicable_to: ["Web", "Node"] }
+applied_in: []
+aliases: [api client, axios alternative, ky, ofetch]
+---
+
+# Fetch Wrapper 설계
+
+> Raw `fetch` 직접 사용 = 매번 인증 / 에러 / 재시도 / 타임아웃 반복. **얇은 wrapper** (또는 ofetch / ky) 가 표준. axios 도 옵션이지만 native fetch 가 가벼움.
+
+## 📖 핵심 개념
+- 단일 baseUrl + 공통 헤더.
+- 자동 인증 헤더 + 401 → refresh.
+- 타임아웃 (AbortSignal.timeout).
+- 재시도 (backoff + retryable).
+- 에러 정규화 (status + body).
+
+## 💻 코드 패턴
+
+### 자체 wrapper
+```ts
+class APIError extends Error {
+  constructor(public status: number, public body: any, message: string) {
+    super(message);
+  }
+}
+
+class APIClient {
+  constructor(private baseUrl: string, private getToken: () => string | null) {}
+
+  async request<T>(path: string, init: RequestInit & { timeout?: number; retries?: number } = {}): Promise<T> {
+    const url = this.baseUrl + path;
+    const { timeout = 10_000, retries = 2, ...rest } = init;
+
+    const headers = new Headers(rest.headers);
+    headers.set('Content-Type', 'application/json');
+    const token = this.getToken();
+    if (token) headers.set('Authorization', `Bearer ${token}`);
+
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await fetch(url, {
+          ...rest,
+          headers,
+          signal: rest.signal ?? AbortSignal.timeout(timeout),
+        });
+        if (res.ok) return await res.json();
+        const body = await res.text();
+        const err = new APIError(res.status, tryParse(body), `${res.status} ${path}`);
+        if (this.isRetryable(res.status) && attempt < retries) {
+          lastErr = err;
+          await wait(200 * Math.pow(2, attempt) + Math.random() * 100);
+          continue;
+        }
+        throw err;
+      } catch (e) {
+        if ((e as Error).name === 'AbortError') throw e;
+        if (attempt === retries) throw e;
+        lastErr = e;
+        await wait(200 * Math.pow(2, attempt));
+      }
+    }
+    throw lastErr;
+  }
+
+  private isRetryable(status: number) {
+    return status === 408 || status === 429 || status >= 500;
+  }
+
+  get<T>(path: string, opts?: RequestInit): Promise<T> { return this.request<T>(path, { ...opts, method: 'GET' }); }
+  post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: JSON.stringify(body) });
+  }
+}
+
+const api = new APIClient('https://api.example.com', () => getAccessToken());
+```
+
+### ofetch / ky (라이브러리)
+```ts
+import { ofetch } from 'ofetch';
+
+const $api = ofetch.create({
+  baseURL: 'https://api.example.com',
+  retry: 2,
+  retryDelay: 200,
+  retryStatusCodes: [408, 429, 500, 502, 503, 504],
+  onRequest({ options }) {
+    options.headers = { ...options.headers, Authorization: `Bearer ${getToken()}` };
+  },
+  async onResponseError({ response }) {
+    if (response.status === 401) await refreshTokenAndRetry();
+  },
+});
+
+const user = await $api<User>('/users/1');
+```
+
+### Schema 검증 결합
+```ts
+import { z } from 'zod';
+const UserS = z.object({ id: z.string(), email: z.string().email() });
+type User = z.infer<typeof UserS>;
+
+async function getUser(id: string): Promise<User> {
+  const raw = await api.get<unknown>(`/users/${id}`);
+  return UserS.parse(raw); // 응답 schema 보장
+}
+```
+
+## 🤔 의사결정 기준
+| 상황 | 도구 |
+|---|---|
+| 작은 프로젝트 | 직접 wrapper (50줄) |
+| Vue / Nuxt | ofetch (Nuxt 표준) |
+| Node + 다양 옵션 | ky 또는 undici |
+| React + cache | tanstack-query + 자체 fetch |
+| GraphQL | graphql-request 또는 Apollo |
+| Streaming (LLM) | fetch + ReadableStream 직접 |
+
+## ❌ 안티packs턴
+- **fetch 매번 직접**: 인증 / 에러 / 재시도 매번 작성.
+- **에러를 throw 안 함**: `if (!res.ok)` 무시 → 빈 body 처리.
+- **JSON 자동 parse 가정**: 4xx body 가 HTML 일 수도. content-type 확인.
+- **AbortSignal 누락**: 떠난 페이지의 요청 계속.
+- **401 무한 retry**: refresh 한 번만 시도.
+- **재시도 시 같은 idempotency key 또는 키 없음**: 중복 처리 위험.
+- **응답 schema 검증 X**: API 형식 변경 시 silent.
+
+## 🤖 LLM 활용 힌트
+- 직접 wrapper 50줄 또는 ofetch.
+- 응답 = zod schema 검증 + brand.
+
+## 🔗 관련 문서
+- [[Backend_Retry_Strategy]]
+- [[Security_Input_Validation]]