본문으로 건너뛰기
STUDY LAB
FrontendLV.2

API · React Query 팩토리 패키지화로 정리한 도메인 기반 서버 상태 관리 구조

API 요청과 React Query 설정을 패키지화하여 도메인 기반 서버 상태 관리 구조를 설계한 과정을 정리했습니다.

프로젝트를 진행하며 느낀 문제#

여러 화면에서 서버 데이터를 가져오고 수정하는 기능이 늘어나기 시작하면서, 처음에는 각 페이지 안에서 직접 API를 호출하고 React Query를 붙이는 방식으로도 충분해 보였습니다. 하지만 기능이 많아지고 화면 수가 늘어날수록, 이 방식은 점점 유지보수하기 어려운 구조가 되었습니다.

특히 고객용 화면과 사장님용 화면이 함께 존재하는 구조에서는, 같은 API를 바라보더라도 각 앱에서 queryKey, queryFn, mutation, 캐시 갱신 방식이 조금씩 다르게 작성되기 시작했습니다. 겉으로는 비슷한 흐름처럼 보여도, 실제로는 데이터 요청 기준과 캐시 처리 규칙이 제각각이어서 구조적인 불일치가 빠르게 쌓였습니다.

  • 컴포넌트마다 직접 axios 호출 로직을 작성
  • queryKey가 화면 단위로 흩어져 일관성이 떨어짐
  • mutation 이후 캐시 갱신 방식이 페이지마다 다르게 작성됨
  • 같은 API를 여러 화면에서 중복 정의하게 됨
  • UI 로직과 서버 상태 관리 로직이 컴포넌트 안에 함께 섞이기 시작함

이런 구조에서는 기능 하나를 수정해도 어느 화면에 영향이 가는지 파악하기 어렵고, 같은 데이터를 다른 화면에서 다르게 다루는 문제가 반복적으로 생겼습니다. 그래서 단순히 API 파일만 분리하는 수준이 아니라, API 호출과 React Query 설정을 도메인 단위 패키지로 정리하고, 서버 상태 관리 규칙을 공통화하는 구조로 다시 설계했습니다.

구조를 어떻게 바꿨는가#

핵심은 다음 두 가지였습니다.

  1. API 호출 레이어를 공통 패키지로 분리하기
  2. React Query를 도메인 기반 팩토리 구조로 통합하기

구조를 정리한 뒤의 흐름은 아래와 같습니다.

plain text
Apps
  ├─ Customer App
  └─ Owner App
 
Packages
  └─ API
       ├─ core
       │    ├─ http
       │    ├─ token-store
       │    ├─ mutation
       │    └─ types
       ├─ models
       └─ domains
            ├─ auth
            ├─ member
            ├─ store
            ├─ order
            ├─ owner
            └─ ...

각 앱은 더 이상 화면 안에서 직접 API를 호출하지 않고, 공통 API 패키지에서 제공하는 도메인 모듈과 query / mutation 팩토리를 가져와 사용하는 방식으로 변경했습니다. 이렇게 하면 화면은 UI와 사용자 흐름에 집중하고, 데이터 요청과 서버 상태 관리는 패키지에서 공통 기준으로 관리할 수 있게 됩니다.

1. API 레이어 패키지화#

가장 먼저 정리한 것은 API 호출 방식이었습니다. 기존에는 각 화면이나 기능 파일 안에서 axios 요청을 직접 작성했지만, 이제는 이를 packages/api로 분리해 공통 레이어로 관리하도록 바꿨습니다.

이 패키지는 단순히 요청 함수만 모아두는 역할이 아니라, 인증 여부에 따라 요청을 구분하고, 토큰을 자동으로 주입하며, 필요한 경우 재발급 로직까지 처리하는 공통 진입점 역할을 하도록 구성했습니다.

  • public / private axios 인스턴스 분리
  • Authorization 헤더 자동 주입
  • 401 응답 시 refresh token 기반 재요청 처리
  • 앱에서 axios 설정을 직접 알 필요 없는 구조로 변경

이 구조 덕분에 각 화면에서는 요청 경로나 인증 처리 방식을 직접 고민하지 않고, 도메인 모듈이 제공하는 요청 함수를 기준으로 기능을 연결할 수 있게 되었습니다.

2. React Query 팩토리 구조 도입#

API만 분리한다고 해서 구조가 완전히 정리되지는 않았습니다. 실제로 더 큰 문제는 React Query 설정이 화면마다 흩어져 있다는 점이었습니다. 같은 도메인을 다루더라도 페이지별로 queryKey, queryFn, mutationFn을 따로 작성하다 보니, 서버 상태 관리 기준이 일관되지 않았습니다.

그래서 각 도메인마다 React Query 팩토리 구조를 도입했습니다. 각 도메인은 아래와 같은 공통 레이어를 가집니다.

plain text
keys        → queryKey 정의
requests    → 실제 API 호출 함수
queries     → queryOptions 기반 조회 팩토리
mutations   → mutationOptions 기반 변경 팩토리
invalidate  → 캐시 무효화 함수

이 구조를 통해 컴포넌트에서는 복잡한 설정을 직접 작성하지 않고, 이미 정의된 query와 mutation을 조합하는 방식으로 사용할 수 있게 되었습니다.

  • queryKey와 queryFn을 함께 캡슐화
  • mutation 정의를 공통 패턴으로 통일
  • 도메인 단위로 상태 관리 책임을 분리
  • 화면 코드에서 비즈니스 로직 비중 감소

3. queryKey 설계 기준 정리#

React Query를 사용하면서 가장 중요하게 봤던 부분 중 하나는 queryKey 설계였습니다. 기존에는 페이지 상황에 따라 key를 임의로 붙이는 경우가 많았고, 이 때문에 어떤 캐시가 어떤 데이터를 의미하는지 한눈에 파악하기 어려웠습니다.

이를 해결하기 위해 queryKey를 도메인 기준 prefix 구조로 통일했습니다. 예를 들어 store 도메인은 아래처럼 계층적으로 설계했습니다.

plain text
["stores"]
["stores", "list"]
["stores", "list", params]
["stores", "detail", storeId]
["stores", "my-store"]

이렇게 정리하면 특정 도메인의 전체 캐시를 무효화하거나, 리스트만, 상세만, 특정 엔티티만 선택적으로 갱신하는 흐름이 훨씬 명확해집니다. 단순히 key를 붙이는 수준이 아니라, 캐시 구조 자체를 도메인 기준으로 설계하게 된 것이 큰 변화였습니다.

  • 도메인 기준 prefix 구조로 queryKey 통일
  • 캐시 범위를 예측 가능하게 관리
  • 중복 key와 불명확한 key 사용 감소
  • mutation 이후 invalidate 범위를 명확하게 지정 가능

4. mutation 이후 캐시 갱신 구조 통합#

조회만 정리한다고 해서 React Query 구조가 완성되는 것은 아니었습니다. 실제로 더 중요한 것은 mutation 이후 서버 상태를 어떻게 화면에 반영할 것인가였습니다. 기존에는 페이지마다 refetch를 하거나, 필요한 곳만 수동으로 invalidate하는 식으로 처리하고 있었기 때문에, 캐시 갱신 방식이 점점 불규칙해졌습니다.

그래서 mutation 성공 이후 관련 캐시를 공통 방식으로 갱신할 수 있도록 helper를 추가했습니다. 핵심은 mutation마다 어떤 캐시를 갱신해야 하는지만 선언하고, 실제 set / merge / invalidate / remove 동작은 공통 로직으로 수행하는 방식입니다.

  • mutation 이후 캐시 갱신 방식을 공통 helper로 정리
  • setQueryData / invalidateQueries / removeQueries 패턴 통합
  • 도메인별로 필요한 캐시 액션만 선언적으로 작성 가능
  • 서버 상태와 화면 상태 간 불일치 감소

이 구조를 통해 수정, 삭제, 생성 이후 어떤 캐시가 바뀌어야 하는지를 매번 화면에서 새로 작성하지 않고, 도메인 레벨에서 일관된 기준으로 관리할 수 있게 되었습니다.

5. 앱과 데이터 레이어의 역할 분리#

구조를 분리하면서 가장 크게 달라진 점은 역할의 경계가 명확해졌다는 점입니다. 이전에는 화면이 API 요청도 하고, 토큰 처리도 알고, queryKey도 정의하고, mutation 이후 refetch까지 담당하는 구조였다면, 이제는 각 레이어가 맡는 책임이 훨씬 선명해졌습니다.

  • API 패키지 → 데이터 요청, 서버 상태 관리, 캐시 규칙 담당
  • 앱 → UI 렌더링, 사용자 인터랙션, 화면 흐름 담당

이렇게 분리하고 나니, 컴포넌트는 “어떤 데이터를 보여줄지”와 “사용자와 어떻게 상호작용할지”에 더 집중할 수 있게 되었고, 서버 상태 관리 로직은 공통 패키지 안에서 더 예측 가능하게 다룰 수 있게 되었습니다.

6. 모노레포 구조와도 자연스럽게 연결된 이유#

이번 구조가 특히 잘 맞았던 이유는, 프로젝트 자체가 customer / owner 두 앱을 함께 관리하는 모노레포 구조였기 때문입니다. 같은 백엔드를 바라보면서도 앱별 화면 요구사항은 다르기 때문에, 공통 API 레이어와 각 앱의 UI 레이어를 분리하는 방식이 구조적으로 자연스러웠습니다.

즉, 데이터 요청 규칙은 공통 패키지에서 관리하고, 실제 화면과 인터랙션은 각 앱에서 조합해 사용하는 방식이 여러 앱을 함께 운영하는 구조에 더 적합했습니다.

  • 여러 앱이 같은 API 구조를 공유 가능
  • 도메인 규칙은 공통 패키지에서 유지
  • 앱별 UI 요구사항은 각 앱 내부에서 분리 관리
  • 확장 시에도 공통 기준을 재사용하기 쉬움

결과적으로 달라진 점#

이번 작업의 핵심은 코드를 한 폴더로 옮긴 것이 아니라, 서버 상태를 다루는 기준 자체를 재정리했다는 점이었습니다. 그 결과 데이터 요청 방식, 캐시 갱신 흐름, 도메인 책임 범위가 훨씬 명확해졌습니다.

  • API 호출 중복 감소
  • React Query 사용 방식 통일
  • 캐시 갱신 구조 단순화
  • 도메인 기준 구조로 확장성 확보
  • 컴포넌트 내부 코드 복잡도 감소
  • 공통 서버 상태 관리 기준 정립

정리#

이번 작업은 단순히 axios 파일을 분리하거나 query를 정리하는 수준의 리팩토링이 아니었습니다. 프로젝트가 커질수록 더 중요해지는 것은, 기능을 어디에 구현하느냐보다 “어떤 기준으로 계속 관리 가능한 구조를 만들 것인가”라고 생각했습니다.

  • API 레이어 패키지화
  • React Query 팩토리 구조 도입
  • queryKey 설계 기준 통일
  • mutation 이후 캐시 갱신 구조 공통화
  • 앱과 서버 상태 관리 레이어 역할 분리

기능은 계속 추가될 수 있지만, 구조가 무너지기 시작하면 이후의 모든 개발 비용이 커집니다. 이번 작업은 여러 화면과 도메인이 함께 자라나는 환경에서, 서버 상태 관리 기준을 코드와 구조로 다시 정리해본 경험이었습니다.

참고#

구현에 사용한 구조와 실제 코드 구성은 아래 저장소를 기반으로 정리했습니다.

GitHub Repository 보기

End of article· 끝까지 읽으면+7 xp

Comments

질문이나 다른 의견이 있다면 남겨주세요. 함께 고민한 내용은 글에 반영합니다.

GitHub으로 의견 남기기