@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/MSW-Mock-/353/215/260/354/235/264/355/204/260-/354/202/254/354/232/251/353/262/225.md

@@ -0,0 +1,579 @@
+# MSW Mock 데이터 사용법
+
+> API 응답 데이터를 자동으로 저장하고 재사용하여, 외부 API 의존도를 줄이고 개발 효율을 높이는 방법
+
+## 📋 개요
+
+이 기능은 MSW(Mock Service Worker)와 IndexedDB를 사용하여:
+- **첫 번째 API 호출**: 실제 API 호출 후 응답 데이터 자동 저장
+- **두 번째부터**: 저장된 mock 데이터 사용 (API 호출 없음)
+- **영구 저장**: 브라우저를 닫아도 데이터 유지
+
+## 🎯 주요 장점
+
+- ✅ **외부 API 차단 대응**: 네트워크 차단 시에도 개발 가능
+- ✅ **빠른 개발**: API 응답을 기다리지 않고 즉시 데이터 사용
+- ✅ **일관된 데이터**: 동일한 테스트 데이터로 반복 작업
+- ✅ **환경별 설정**: `.env` 파일로 쉽게 ON/OFF 제어
+
+## 🚀 적용 방법
+
+### 1. MSW 설치
+
+```bash
+npm install msw --save-dev
+```
+
+### 2. MSW Service Worker 초기화
+
+```bash
+npx msw init public/ --save
+```
+
+### 3. 필수 파일 생성
+
+#### `src/mocks/storage/mockStorage.ts`
+
+IndexedDB를 사용한 mock 데이터 저장소:
+
+```typescript
+const DB_NAME = 'msw-mock-data';
+const DB_VERSION = 1;
+const STORE_NAME = 'api-responses';
+
+let db: IDBDatabase | null = null;
+
+const initDB = (): Promise<IDBDatabase> => {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => {
+      db = request.result;
+      resolve(db);
+    };
+
+    request.onupgradeneeded = (event) => {
+      const database = (event.target as IDBOpenDBRequest).result;
+      if (!database.objectStoreNames.contains(STORE_NAME)) {
+        database.createObjectStore(STORE_NAME, { keyPath: 'key' });
+      }
+    };
+  });
+};
+
+export const saveMockData = async (key: string, data: unknown): Promise<void> => {
+  if (!db) await initDB();
+
+  const transaction = db!.transaction([STORE_NAME], 'readwrite');
+  const objectStore = transaction.objectStore(STORE_NAME);
+
+  objectStore.put({ key, data, timestamp: Date.now() });
+};
+
+export const getMockData = async (key: string): Promise<unknown | null> => {
+  if (!db) await initDB();
+
+  const transaction = db!.transaction([STORE_NAME], 'readonly');
+  const objectStore = transaction.objectStore(STORE_NAME);
+  const request = objectStore.get(key);
+
+  return new Promise((resolve) => {
+    request.onsuccess = () => {
+      const record = request.result;
+      resolve(record ? record.data : null);
+    };
+    request.onerror = () => resolve(null);
+  });
+};
+
+export const generateKey = (method: string, url: string, params?: Record<string, unknown>): string => {
+  const normalizedMethod = method.toUpperCase();
+  const normalizedUrl = url.split('?')[0]; // 쿼리 파라미터 제거
+
+  if (params && Object.keys(params).length > 0) {
+    // 객체를 안전하게 쿼리 문자열로 변환
+    const searchParams = new URLSearchParams();
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        searchParams.append(key, String(value));
+      }
+    });
+
+    const paramString = searchParams.toString();
+    return `${normalizedMethod}:${normalizedUrl}:${paramString}`;
+  }
+
+  return `${normalizedMethod}:${normalizedUrl}`;
+};
+
+// 백업용: 모든 데이터 조회
+export const getAllMockData = async (): Promise<Record<string, unknown>> => {
+  // ... IndexedDB에서 모든 데이터 가져오기
+};
+
+// 리스토어용: 여러 데이터 한 번에 저장
+export const saveMultipleMockData = async (dataMap: Record<string, unknown>): Promise<void> => {
+  // ... IndexedDB에 여러 데이터 저장
+};
+```
+
+#### `src/mocks/apiWrapperMock.ts`
+
+apiWrapper용 mock 데이터 관리:
+
+```typescript
+import { getMockData, generateKey, saveMockData } from './storage/mockStorage';
+
+export interface ApiWrapperMockOptions {
+  useMock?: boolean;
+  method: string;
+  route: string;
+  body?: any;
+}
+
+export const useMockDataIfNeeded = async <T>(
+  options: ApiWrapperMockOptions,
+): Promise<{ data: T | null; shouldCallApi: boolean }> => {
+  if (import.meta.env.VITE_MSW_ENABLED !== 'true') {
+    return { data: null, shouldCallApi: true };
+  }
+
+  const { method, route, body } = options;
+  const key = generateKey(method, route, body);
+
+  try {
+    const mockData = await getMockData(key);
+
+    if (mockData) {
+      console.log(`[apiWrapper Mock] ✅ Using cached data for: ${key}`);
+      return { data: mockData as T, shouldCallApi: false };
+    }
+
+    console.log(`[apiWrapper Mock] ⏳ No cached data for: ${key}`);
+    return { data: null, shouldCallApi: true };
+  } catch (error) {
+    console.error('[apiWrapper Mock] Failed to get mock data:', error);
+    return { data: null, shouldCallApi: true };
+  }
+};
+
+export const saveMockResponseIfNeeded = async (
+  options: ApiWrapperMockOptions,
+  data: unknown,
+) => {
+  if (import.meta.env.VITE_MSW_ENABLED !== 'true') {
+    return;
+  }
+
+  const { method, route, body } = options;
+  const key = generateKey(method, route, body);
+
+  try {
+    await saveMockData(key, data);
+    console.log(`[apiWrapper Mock] 💾 Saved mock data for: ${key}`);
+  } catch (error) {
+    console.error('[apiWrapper Mock] Failed to save mock data:', error);
+  }
+};
+```
+
+#### `src/mocks/handlers/index.ts`
+
+MSW 핸들러 (빈 핸들러로 유지):
+
+```typescript
+import { http } from 'msw';
+
+export const handlers = [
+  // 실제 mock 처리는 apiWrapper에서 수행
+];
+```
+
+#### `src/mocks/browser.ts`
+
+MSW 브라우저 워커:
+
+```typescript
+import { setupWorker } from 'msw/browser';
+import { handlers } from './handlers';
+
+type SetupWorker = ReturnType<typeof setupWorker>;
+
+let worker: SetupWorker | null = null;
+
+export const createMockWorker = (): SetupWorker => {
+  if (worker) {
+    return worker;
+  }
+
+  worker = setupWorker(...handlers);
+  return worker;
+};
+```
+
+#### `src/mocks/devtools.ts`
+
+개발자 도구 유틸리티:
+
+```typescript
+import {
+  getAllMockKeys,
+  getMockData,
+  deleteMockData,
+  clearAllMockData,
+  getAllMockData,
+  saveMultipleMockData,
+} from './storage/mockStorage';
+
+export interface MSWDevTools {
+  list: () => Promise<string[]>;
+  get: (key: string) => Promise<unknown>;
+  delete: (key: string) => Promise<void>;
+  clear: () => Promise<void>;
+  backup: () => Promise<void>;
+  restore: () => Promise<void>;
+  help: () => void;
+}
+
+export const setupMSWDevTools = () => {
+  if (import.meta.env.DEV) {
+    const mswDevTools: MSWDevTools = {
+      list: async () => {
+        const keys = await getAllMockKeys();
+        console.log(`[MSW DevTools] Total ${keys.length} cached APIs:`);
+        console.table(keys.map((key) => ({ key })));
+        return keys;
+      },
+
+      get: async (key: string) => {
+        const data = await getMockData(key);
+        if (data) {
+          console.log(`[MSW DevTools] Data for: ${key}`, data);
+        } else {
+          console.warn(`[MSW DevTools] No data found for: ${key}`);
+        }
+        return data;
+      },
+
+      delete: async (key: string) => {
+        await deleteMockData(key);
+        console.log(`[MSW DevTools] Deleted: ${key}`);
+      },
+
+      clear: async () => {
+        await clearAllMockData();
+        console.log('[MSW DevTools] All mock data cleared!');
+      },
+
+      backup: async () => {
+        try {
+          const dataMap = await getAllMockData();
+          const keys = Object.keys(dataMap);
+
+          if (keys.length === 0) {
+            console.warn('[MSW DevTools] No data to backup!');
+            return;
+          }
+
+          // JSON 파일 생성 및 다운로드
+          const jsonString = JSON.stringify(dataMap, null, 2);
+          const blob = new Blob([jsonString], { type: 'application/json' });
+          const url = URL.createObjectURL(blob);
+
+          const link = document.createElement('a');
+          link.href = url;
+          const date = new Date().toISOString().split('T')[0];
+          link.download = `msw-mock-backup-${date}.json`;
+          document.body.appendChild(link);
+          link.click();
+          document.body.removeChild(link);
+          URL.revokeObjectURL(url);
+
+          console.log(`[MSW DevTools] ✅ Backup complete: ${keys.length} entries saved`);
+        } catch (error) {
+          console.error('[MSW DevTools] Failed to backup:', error);
+        }
+      },
+
+      restore: async () => {
+        try {
+          const input = document.createElement('input');
+          input.type = 'file';
+          input.accept = 'application/json';
+
+          input.onchange = async (event) => {
+            const file = (event.target as HTMLInputElement).files?.[0];
+            if (!file) return;
+
+            try {
+              const text = await file.text();
+              const dataMap = JSON.parse(text);
+
+              // 기존 데이터 삭제 후 복원
+              await clearAllMockData();
+              await saveMultipleMockData(dataMap);
+
+              console.log(`[MSW DevTools] ✅ Restore complete: ${Object.keys(dataMap).length} entries restored!`);
+              console.log('[MSW DevTools] 💡 Recommended: Refresh the page to apply changes.');
+            } catch (error) {
+              console.error('[MSW DevTools] Failed to restore:', error);
+            }
+          };
+
+          input.click();
+        } catch (error) {
+          console.error('[MSW DevTools] Failed to restore:', error);
+        }
+      },
+
+      help: () => {
+        console.log(`
+[MSW DevTools] 사용법:
+
+  window.mswDevTools.list()                    # 저장된 모든 mock 데이터 키 목록
+  window.mswDevTools.get('GET:/ao/api/users') # 특정 mock 데이터 조회
+  window.mswDevTools.delete('GET:/ao/api/users') # 특정 mock 데이터 삭제
+  window.mswDevTools.clear()                  # 모든 mock 데이터 삭제
+  window.mswDevTools.backup()                 # JSON 파일로 백업 (다운로드)
+  window.mswDevTools.restore()                # JSON 파일에서 리스토어 (파일 선택)
+
+예시:
+  // 백업 생성
+  await window.mswDevTools.backup()
+
+  // 리스토어
+  await window.mswDevTools.restore()
+
+  // 모든 저장된 API 목록 보기
+  await window.mswDevTools.list()
+        `);
+      },
+    };
+
+    (window as unknown as { mswDevTools: MSWDevTools }).mswDevTools = mswDevTools;
+    console.log('[MSW DevTools] initialized. Type window.mswDevTools.help() for usage.');
+  }
+};
+```
+
+### 4. apiWrapper 수정
+
+`src/services/apiWrapper.ts`의 `apiWrapper` 함수에 mock 데이터 확인 로직 추가:
+
+```typescript
+export const apiWrapper: ApiWrapper = async <P>(
+  method: ApiMethod,
+  route: string,
+  body?: any,
+  config: ApiRequestConfig = {},
+) => {
+  // ... 기존 코드 ...
+
+  // MSW Mock 데이터 확인 (apiWrapper 레벨에서 직접 처리)
+  if (import.meta.env.DEV && import.meta.env.VITE_MSW_ENABLED === 'true') {
+    try {
+      const { useMockDataIfNeeded } = await import("../mocks/apiWrapperMock");
+      const { data: mockData, shouldCallApi } = await useMockDataIfNeeded<P>({
+        method,
+        route,
+        body,
+      });
+
+      if (!shouldCallApi && mockData) {
+        // mock 데이터가 있으면 반환
+        return { data: mockData, headers: {}, ...{} as any };
+      }
+    } catch (error) {
+      console.error('[apiWrapper] Failed to check mock data:', error);
+    }
+  }
+
+  try {
+    const { data, headers, ...rest } = await _axios(apiDataPlugin(axiosConfig));
+    // ... 기존 에러 처리 코드 ...
+
+    // 성공 응답 시 mock 데이터 저장
+    const { saveMockResponseIfNeeded } = await import("../mocks/apiWrapperMock");
+    const mockKey = generateKey(method, route, body);
+    saveMockResponseIfNeeded({ method, route, body }, data);
+  }
+  // ... catch 코드 ...
+};
+```
+
+### 5. main.tsx 수정
+
+```typescript
+// MSW (Mock Service Worker) - 개발 환경에서만 활성화
+const initializeMSW = async () => {
+  if (import.meta.env.DEV && import.meta.env.VITE_MSW_ENABLED === 'true') {
+    const { createMockWorker } = await import('./mocks/browser');
+    const { setupMSWDevTools } = await import('./mocks/devtools');
+    const worker = createMockWorker();
+
+    try {
+      await worker?.start({
+        onUnhandledRequest: 'bypass',
+      });
+      console.log('[MSW] Mock Service Worker started successfully');
+
+      setupMSWDevTools();
+    } catch (error) {
+      console.error('[MSW] Failed to start Mock Service Worker:', error);
+    }
+  }
+};
+
+// MSW 초기화 후 앱 렌더링
+initializeMSW().then(() => {
+  ReactDOM.createRoot(document.getElementById("root")!).render(
+    // ... 앱 렌더링 코드 ...
+  );
+});
+```
+
+### 6. 환경 변수 설정
+
+`.env.dev`, `.env.alpha`, `.env.beta` 등에 추가:
+
+```bash
+# MSW (Mock Service Worker) 설정
+VITE_MSW_ENABLED=true
+```
+
+### 7. package.json 업데이트
+
+`npx msw init public/ --save` 명령어 실행 후 `package.json`에 자동 추가됨:
+
+```json
+{
+  "msw": {
+    "workerDirectory": "public"
+  }
+}
+```
+
+## 🛠️ 사용 방법
+
+### 1. MSW 활성화
+
+`.env.alpha` 등 환경 파일에서 `VITE_MSW_ENABLED=true`로 설정:
+
+```bash
+VITE_MSW_ENABLED=true
+```
+
+### 2. 개발 서버 시작
+
+```bash
+npm run dev:alpha
+```
+
+### 3. DevTools 사용
+
+브라우저 개발자 도구 콜솔에서:
+
+```javascript
+// 저장된 모든 API 목록
+await window.mswDevTools.list()
+
+// 특정 API 데이터 조회
+await window.mswDevTools.get('POST:/ao/api/login/otp/sms:usrLoginId=system&usrPw=...')
+
+// 특정 API 데이터 삭제
+await window.mswDevTools.delete('POST:/ao/api/login/otp/sms:...')
+
+// 모든 데이터 삭제
+await window.mswDevTools.clear()
+
+// 💾 백업 (JSON 파일 다운로드)
+await window.mswDevTools.backup()
+
+// 📂 리스토어 (JSON 파일 선택창 열림)
+await window.mswDevTools.restore()
+
+// 도움말
+window.mswDevTools.help()
+```
+
+### 4. 백업 & 리스토어
+
+#### 백업 (Backup)
+
+IndexedDB에 저장된 모든 mock 데이터를 JSON 파일로 다운로드합니다:
+
+```javascript
+await window.mswDevTools.backup()
+```
+
+- 파일명: `msw-mock-backup-YYYY-MM-DD.json`
+- 모든 API 응답 데이터가 포함됩니다
+- 팀원들과 공유하거나 다른 PC에서 사용 가능
+
+#### 리스토어 (Restore)
+
+백업된 JSON 파일을 불러와서 IndexedDB에 복원합니다:
+
+```javascript
+await window.mswDevTools.restore()
+```
+
+1. 파일 선택창이 열립니다
+2. 백업 파일을 선택하면 자동으로 복원됩니다
+3. 복원 후 페이지 새로고침을 권장합니다
+
+**주의사항:**
+- 리스토어 시 **기존 데이터는 모두 삭제**됩니다
+- 다른 프로젝트에서 백업한 파일도 사용 가능합니다 (경로가 동일한 경우)
+
+## 📁 파일 구조
+
+```
+src/mocks/
+├── browser.ts                    # MSW 브라우저 워커 설정
+├── handlers/
+│   └── index.ts                  # MSW 핸들러 (비어있음)
+├── storage/
+│   └── mockStorage.ts            # IndexedDB 저장소
+├── apiWrapperMock.ts             # apiWrapper용 mock 유틸리티
+└── devtools.ts                   # 개발자 도구
+
+public/
+└── mockServiceWorker.js          # MSW 서비스 워커 (자동 생성)
+```
+
+## 🔑 API 데이터 키 형식
+
+```
+METHOD:/API/path:param1=value1&param2=value2
+
+예시:
+GET:/ao/api/users:pageNumber=1&pageSize=20
+POST:/ao/api/users/save
+POST:/ao/api/login/otp/sms:usrLoginId=system&usrPw=...&otpNum=123456
+```
+
+## 💡 주의사항
+
+1. **로그인 API**: 보안상 로그인 관련 API도 mock으로 저장됩니다. 실제 로그인 테스트 시 주의하세요.
+2. **데이터 무결성**: mock 데이터는 실제 API 응답을 저장하므로, 백엔드 데이터 변경 시 `window.mswDevTools.clear()`로 초기화하세요.
+3. **개발 전용**: 이 기능은 개발 환경에서만 사용하세요. 프로덕션 빌드에서는 자동으로 비활성화됩니다.
+4. **CORS 문제**: apiWrapper 레벨에서 mock을 처리하므로 CORS 문제가 발생하지 않습니다.
+
+## 🎯 적용 후 효과
+
+### Before (MSW 미적용)
+- 외부 API 차단 시 개발 불가
+- 매번 실제 API 호출 대기
+- 네트워크 지연으로 개발 속도 저하
+
+### After (MSW 적용)
+- 외부 API 차단 시에도 개발 가능
+- 첫 호출 이후 즉시 mock 데이터 사용
+- 일관된 테스트 데이터로 빠른 개발
+
+---
+
+*이 가이드는 실제 프로젝트에 적용된 MSW Mock 데이터 기능을 정리한 것입니다.*