muroom 프로젝트에서 기술적 도전 과제가 가장 컸던 지점은 단연 지도 기반의 통합 검색 시스템이었다. 가격, 크기, 옵션 등 20여 개의 필터와 지도 좌표를 실시간으로 동기화하는 작업은 결코 만만치 않았다. 이는 단순히 상태를 관리하는 문제를 넘어, 성능 최적화와 사용자 경험(UX) 사이에서 발생하는 기술적 트레이드오프를 해결하고 가장 효율적인 데이터 흐름을 설계하는 과정이었다.

1. 난생처음 보는 파라미터 갯수: 20개의 파라미터와 복잡한 요구사항

지도 기반 서비스의 핵심은 사용자가 보고 있는 영역과 필터 조건에 맞는 데이터를 즉시, 그리고 정확하게 보여주는 것이다. 하지만 muroom 개발 과정에서 마주한 데이터의 양은 상상을 초월했다. 단순히 '탐색' 기능이라 부르기엔 관리해야 할 상태값이 너무나 방대했기 때문이다.

구체적으로 한 화면에서 동기화되어야 할 데이터는 다음과 같았다.

• 지도 영역(Bounds): 현재 보고 있는 영역을 결정하는 minLat, maxLat, minLng, maxLng
• 검색 및 정렬: 유저의 입력 키워드(keyword)와 데이터 정렬 기준(sort)
• 복합 필터: 가격 범위(Min/Max), 방의 제원(가로/세로/높이), 층수, 화장실 타입, 주차/숙식 가능 여부, 화재 보험 가입 여부, 금지 악기 리스트 등

❓ 왜 전역 상태(Zustand 등)만으로는 부족했을까?

처음에는 익숙한 Zustand 같은 메모리 기반 전역 상태를 떠올릴 수도 있었지만, 다음과 같은 명확한 한계가 존재했다.

1. 휘발성 데이터의 한계: 전역 상태는 페이지를 새로고침하는 순간 모든 값이 초기화된다. 사용자가 정성껏 맞춘 20개의 필터가 새로고침 한 번에 날아가는 것은 사용자 경험(UX) 측면에서 치명적이다.
2. 공유 및 재현 불가능: 특정 검색 결과의 URL을 친구에게 공유했을 때, 전역 상태에만 데이터가 들어있다면 상대방은 빈 지도만 보게 된다. "내가 보던 화면 그대로"를 전달할 수 없다는 뜻이다.
3. 브라우저 히스토리와의 충돌: 사용자가 필터를 바꿨다가 '뒤로 가기'를 눌렀을 때, 전역 상태는 이전 필터 값을 기억하지 못한다. 주소창은 바뀌는데 화면 데이터는 그대로인 '상태 불일치' 현상이 발생하기 쉽다.
4. 상태 동기화의 복잡도: 만약 URL과 전역 상태를 동시에 쓰려고 한다면, 두 상태를 일치시키기 위한 수많은 useEffect와 예외 처리 로직이 필요해지며 이는 곧 코드의 복잡도 상승으로 이어진다.

결국 이 방대한 데이터를 '어떻게 유실 없이 관리하고, 수많은 파라미터 변화에도 성능을 유지할 것인가' 가 이번 설계의 가장 큰 숙제였다.

2. 왜 URL 상태 관리(nuqs)였을까?

나는 모든 상태의 Single Source of Truth 를 주소창(URL)으로 설정했다. 여기에는 세 가지 전략적 이유가 있었다.

1. UX의 연속성: 사용자가 설정한 필터 그대로 링크 공유가 가능하고, 새로고침 시에도 이전 검색 맥락이 100% 유지된다.
2. 반응형 대응의 간소화: 모바일과 데스크톱의 레이아웃이 극명하게 달랐다. 각기 다른 컴포넌트에서 동일한 상태를 참조해야 할 때, URL에서 값을 꺼내 쓰는 방식이 Props Drilling이나 복잡한 전역 상태 선언보다 훨씬 명확했다.
3. 선언적 데이터 페칭: URL이 바뀌면 queryKey가 자동으로 변경되어 데이터를 다시 불러오는 구조를 택함으로써, 불필요한 명령형(useEffect) 로직을 최소화했다.

3. 기술적 최적화: Shallow Routing & Batching

20개가 넘는 파라미터를 주소창에 넣을 때 가장 큰 적은 '렌더링 오버헤드' 와 '히스토리 꼬임' 이다. 이를 해결하기 위해 두 가지 핵심 최적화를 적용했다.

⚡ Shallow Routing으로 서버 부하 줄이기

nuqs의 shallow: true 옵션을 적극 활용했다. URL이 바뀔 때마다 Next.js가 서버로 페이지 전체를 요청하는 대신, 브라우저의 주소창만 기민하게 업데이트하도록 설정했다.

주소창은 바뀌지만 'Doc' 타입의 요청 없이 API 통신만 일어나는 모습.

📦 배치(Batching) 업데이트로 히스토리 관리

지도 영역이 바뀔 때 좌표값 4개(minLat, maxLat 등)를 각각 따로 업데이트하면 브라우저 히스토리에 불필요한 스택이 쌓이고 주소창이 덜컥거리는 현상이 발생한다. 이를 방지하기 위해 useQueryStates를 사용하여 여러 파라미터를 단 한 번의 업데이트로 묶어서 처리하는 배치 방식을 도입했다.

// 단 한 번의 업데이트로 7개의 지도 파라미터를 동시에 반영 (Batching)
setParams({
  center: state.center,
  zoom: state.zoom,
  studioId: state.studioId,
  minLatitude: state.bounds?.minLat ?? null,
  // ...나머지 좌표 데이터
});

지도가 멈추는 순간 7개의 데이터가 한 묶음으로 깔끔하게 처리되는 로그.

4. TanStack Query와 UX의 디테일: 끊김 없는 탐색

물리적인 성능 최적화만큼 중요했던 것은 데이터를 불러오는 동안 사용자가 느끼는 '체감 속도' 였다.

🔄 keepPreviousData: 부드러운 화면 전환의 비밀

데스크톱의 페이지네이션이나 모바일의 무한 스크롤 환경에서, 새 데이터를 가져올 때마다 화면이 하얗게 비워진다면 사용자는 큰 피로감을 느낀다. 나는 TanStack Query의 keepPreviousData 옵션을 활용해 이 문제를 해결했다.

데스크톱 페이지네이션	모바일 무한 스크롤

로딩 중에도 이전 리스트를 그대로 유지하여 깜빡임 없는 사용자 경험을 제공한다.

🛠️ 하이브리드 페칭 로직 구현

muroom은 하나의 커스텀 훅(useStudiosMapListInfiniteQuery)에서 모바일의 무한 스크롤과 데스크톱의 페이지네이션을 동시에 대응하도록 설계했다. 핵심은 placeholderData를 통해 데이터 공백을 메우는 것이다.

const useStudiosMapListInfiniteQuery = (
  params: StudiosMapSearchRequestProps | undefined,
  config: { page: number; size: number; isMobile: boolean; }
) => {
  return useInfiniteQuery({
    queryKey: [
      'studios', 'map-list',