한 프론트엔드 팀이 개발 환경에서만 작동하는 타입 안정성이 보장된 API 모킹 레이어를 도입했습니다. Axios 인터셉터와 Vite의 트리 쉐이킹(tree-shaking)을 활용하여 프로덕션 번들에는 아무런 영향을 주지 않습니다. 엔지니어들은 백엔드 엔드포인트가 완성되기를 기다리는 동안 평소와 같은 패턴으로 데이터를 가져오고, 환경 변수 플래그 하나만 바꾸면 실제 API를 호출할 수 있습니다.

팀이 더 나은 모킹 방식이 필요했던 이유

백엔드 라우트가 미완성일 때 프론트엔드 개발자들은 난관에 봉착합니다. 컴포넌트 내부에 응답을 하드코딩하거나 UI 곳곳에 if (process.env.NODE_ENV === 'development') 블록을 뿌리는 식의 임시방편은 앱 개발을 계속 진행할 수는 있게 해주지만 기술 부채를 남깁니다. 이러한 모킹 객체들은 컴포넌트 로직의 일부가 되어 프로덕션에 가짜 데이터가 배포될 위험을 높이고, 코드를 읽고 테스트하기 어렵게 만듭니다.

팀은 모든 모킹 로직을 컴포넌트 트리 밖으로 분리하고, 프론트엔드와 백엔드 간의 계약(contract)을 강제하며, 프로덕션 빌드에 불필요한 코드가 포함되지 않도록 보장하기를 원했습니다.

팀이 따르는 3단계 프로세스

  1. 계약 미팅(Contract meeting) – 프론트엔드와 백엔드 엔지니어가 모여 각 요청의 URL, 메서드, 예상 페이로드를 나열합니다.
  2. 타입이 지정된 계약(Typed contract) – 나열된 목록을 TypeScript 인터페이스로 변환하여, 요청과 응답 형태에 대한 단일 진실 공급원(single source of truth)으로 삼습니다.
  3. 인터셉터 연결(Interceptor wiring) – Axios 인터셉터가 모든 나가는 요청을 검사합니다. URL이 등록된 모킹과 일치하면 인터셉터가 모킹 데이터를 반환하고, 그렇지 않으면 요청은 실제 서버로 전달됩니다.

인터셉터가 모킹 로직이 존재하는 유일한 장소이기 때문에 컴포넌트 코드는 변경되지 않습니다. 개발자들은 별도의 조건부 로직을 추가할 필요 없이 useQuery와 같은 기존의 데이터 페칭 훅을 그대로 사용할 수 있습니다.

프로덕션 번들 비대화를 방지하는 방법

팀은 Vite에서 사용하는 번들러인 Rollup이 프로덕션 빌드 시 모킹 코드를 완전히 제거할 수 있도록 세 가지 안전장치를 마련했습니다.

  • import.meta.env.DEV는 프로덕션 빌드에서 false로 해석되므로, 트리 쉐이킹 과정에서 인터셉터 모듈 전체가 사라집니다.
  • 유닛 테스트를 실행할 때는 MODE 변수가 test 이외의 값으로 설정되어, 테스트 전용 코드가 분리됩니다.
  • 커스텀 플래그인 VITE_ENABLE_MSW는 기본값이 false이며, 모킹을 활성화하려면 명시적으로 켜야 합니다.

이 세 가지 조건이 모두 false이면 모킹 레지스트리는 최종 번들에 포함되지 않습니다.

모킹 파일 구성

저장소는 기능 중심(feature-centric) 레이아웃을 따릅니다.

  • interfaces/ – 계약 미팅을 통해 생성된 TypeScript 정의를 보관합니다.
  • scenarios.ts – 각 엔드포인트에 대한 성공적인 응답과 에러 케이스의 구체적인 예시를 포함합니다.
  • devHandlers.ts – URL을 시나리오 데이터에 매핑하고 인터셉터를 Axios에 연결하는 중앙 레지스트리 역할을 합니다.

작은 스캐폴딩 스크립트를 통해 이 파일들을 자동으로 생성할 수 있습니다. URL과 일치하는 인터페이스를 입력하면 스텁(stub) 파일을 생성하고 모킹을 등록합니다. 이 스크립트는 프로덕션 코드 경로 외부에 존재하므로 번들 크기에 영향을 주지 않습니다.

팀이 얻은 이점

  • 컴포넌트 내부 모킹 제로 – 모든 가짜 데이터는 전용 레이어에 존재하므로 UI 코드가 깔끔하게 유지됩니다.
  • 엔드 투 엔드 타입 안정성 – 모킹 데이터가 실제 응답에 사용되는 것과 동일한 TypeScript 인터페이스를 따르므로, 불일치 문제를 컴파일 단계에서 잡아낼 수 있습니다.
  • 프로덕션 부하 없음 – 트리 쉐이킹이 인터셉터와 모킹 데이터를 완전히 제거하여 번들 크기에 변화가 없습니다.
  • 개발 및 테스트를 위한 공유 시나리오 – 동일한 모킹 정의가 로컬 개발과 자동화된 테스트 모두에 사용되어 중복을 줄입니다.

트레이드오프와 한계

이 방식이 실제 백엔드를 대체할 수는 없습니다. 모킹 계약이 실제 API와 달라지면, 개발자는 환경 변수 플래그를 바꾼 후에야 불일치를 발견하게 됩니다.

향후 주목할 점

  • 도구 통합(Tooling integration) –
  • 더 넓은 도입(Broader adoption) –
  • 성능 모니터링(Performance monitoring) –

핵심은 명확합니다. 모킹 로직을 타입이 지정되고 환경에 따라 제어되는 레이어로 옮기면, 프론트엔드 팀은 컴포넌트를 깨끗하게 유지하고 타입 안정성을 확보하며, 숨겨진 모킹 페이로드 없이 프로덕션 빌드를 배포할 수 있습니다. 공유된 계약을 유지하는 것은 더 원활한 개발 워크플로우와 깨끗한 코드베이스를 위한 대가입니다.