[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,101 @@
+---
+id: web-service-worker-patterns
+title: Service Worker 캐싱 전략
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [web, service-worker, pwa, caching, offline, vibe-coding]
+tech_stack: { language: "TypeScript / Workbox", applicable_to: ["Web", "PWA"] }
+applied_in: []
+aliases: [cache-first, network-first, stale-while-revalidate, PWA]
+---
+
+# Service Worker 캐싱 전략
+
+> Service Worker = 네트워크 인터셉터. 5가지 표준 전략 — Cache-First / Network-First / Stale-While-Revalidate / Network-Only / Cache-Only — 자원 종류에 따라 골라 쓴다. 한 SW 안에 여러 전략 혼용 OK.
+
+## 📖 핵심 개념
+- `install` 이벤트: precache (빌드 시 알려진 자원).
+- `fetch` 이벤트: 매 요청 인터셉트.
+- `activate` 이벤트: 옛 캐시 청소.
+- 자원 별 다른 정책 적용.
+
+## 💻 코드 패턴 (Workbox 기반)
+
+```ts
+// sw.ts
+import { precacheAndRoute } from 'workbox-precaching';
+import { registerRoute } from 'workbox-routing';
+import { CacheFirst, NetworkFirst, StaleWhileRevalidate } from 'workbox-strategies';
+import { ExpirationPlugin } from 'workbox-expiration';
+
+// 빌드 시 자동 주입
+precacheAndRoute(self.__WB_MANIFEST);
+
+// 1. 정적 자산 — Cache-First (해시 파일명이라 immutable)
+registerRoute(
+  ({ request }) => ['style', 'script', 'font'].includes(request.destination),
+  new CacheFirst({
+    cacheName: 'static-v1',
+    plugins: [new ExpirationPlugin({ maxAgeSeconds: 30 * 24 * 60 * 60 })],
+  })
+);
+
+// 2. 이미지 — Stale-While-Revalidate
+registerRoute(
+  ({ request }) => request.destination === 'image',
+  new StaleWhileRevalidate({
+    cacheName: 'images-v1',
+    plugins: [new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 7 * 24 * 60 * 60 })],
+  })
+);
+
+// 3. API — Network-First with timeout
+registerRoute(
+  ({ url }) => url.pathname.startsWith('/api/'),
+  new NetworkFirst({
+    cacheName: 'api-v1',
+    networkTimeoutSeconds: 3,
+  })
+);
+```
+
+### 5가지 전략 요약
+| 전략 | 흐름 | 사용처 |
+|---|---|---|
+| Cache-First | 캐시 → 없으면 네트워크 | hashed 정적 자산 |
+| Network-First | 네트워크 → 실패시 캐시 | 자주 변하는 데이터 |
+| Stale-While-Revalidate | 캐시 즉시 + 백그라운드 재검증 | 이미지, 자주 보지만 약간 stale OK |
+| Network-Only | 캐시 안 씀 | 결제, 민감 데이터 |
+| Cache-Only | 네트워크 안 씀 | 오프라인 전용 자원 |
+
+## 🤔 의사결정 기준
+| 자원 | 전략 |
+|---|---|
+| JS/CSS (hashed) | Cache-First + 만료 30d |
+| 이미지 | Stale-While-Revalidate + 100 entries cap |
+| HTML | Network-First (3s timeout) → cached fallback |
+| API GET (read) | Network-First or stale-while-revalidate |
+| API POST (write) | Network-Only (절대 캐시 X) |
+| Offline page | Cache-Only |
+
+## ❌ 안티패턴
+- **모든 요청 Cache-First**: API 응답이 영원히 stale. 사용자 답답.
+- **버전 관리 없는 캐시 이름**: 새 deploy 가 옛 캐시 못 청소. `static-v1` → `static-v2`.
+- **POST 요청 캐싱**: 사고. 명시적 Network-Only.
+- **manifest 없는 precache**: 빌드 타임 정보 안 들어가서 누락.
+- **`activate` 에서 옛 캐시 안 지움**: 무한 누적 → quota exceeded.
+- **localhost 에서 SW 등록 후 디버깅 어려움**: chrome devtools "Update on reload" + "Bypass for network" 활용.
+- **사용자 알림 없이 새 SW 활성화**: 페이지가 갑자기 다른 버전. `skipWaiting` + `clientsClaim` 신중히. 보통 사용자에게 "새 버전 있음, 새로고침" prompt.
+
+## 🤖 LLM 활용 힌트
+- Workbox 또는 vite-plugin-pwa 사용 가정.
+- 자원 별 전략 매핑 표를 먼저 만들고 코드 작성.
+- 새 SW 활성화는 사용자 동의 후 (UX 보호).
+
+## 🔗 관련 문서
+- [[Web_HTTP_Cache_Headers]]
+- [[Backpressure_Patterns]]