사내 보안 리소스 통합 플랫폼 구축기 : 3. URL을 중심으로 설계한 필터, 검색, 페이지네이션 상태 관리 전략

이번 글에서는 체커 목록 화면에서 필터, 검색, 페이지네이션 상태를 어떻게 관리했는지 정리하고자 한다.
특히 Next.js 기반 환경에서 URL 쿼리 파라미터를 중심으로 상태를 통합 관리하고,
이를 React Query와 서버 사이드 렌더링(SSR)까지 연결해 일관된 UX와 초기 성능을 확보하는 전략을 설계했다.
 

🔍 문제 정의

처음에는 필터와 검색 상태를 전역 상태로 관리하거나 localStorage에 저장하는 방식을 고려했었다.
하지만 아래와 같은 실질적인 한계점이 존재했다.

• 페이지를 새로고침하면 상태가 초기화되어 사용성이 떨어짐
• 필터링된 상태를 URL로 공유할 수 없어 협업 시 불편함
• 브라우저 뒤로가기/앞으로가기 동작이 기대와 다르게 작동함
• SSR을 활용한 초기 렌더링과 연결되지 않아 로딩 시 UX가 좋지 않음

이러한 문제를 해결하기 위해, URL 쿼리 기반의 상태 관리 방식으로 전환했다.
 

✅ 해결 방향: useSearchParams 기반의 URL 상태 동기화

Next.js의 useSearchParams를 활용해 필터 상태, 검색어, 페이지네이션 정보를 URL 쿼리로 직접 관리하도록 구성했다.
이 방식은 다음과 같은 장점을 제공했다.

• 새로고침 시에도 상태가 유지됨
• 필터링된 화면을 URL로 공유할 수 있음
• 브라우저 히스토리와 자동으로 연동되어 UX가 자연스러움
• SSR에서도 동일한 쿼리 기반으로 데이터를 사전 로딩할 수 있어 초기 렌더링 성능이 향상됨

 

⚙️ 주요 구현 내용

해당 코드들은 예시 코드들로 변경하여 작성되었습니다.

1. URL 파라미터 업데이트 함수

쿼리 파라미터는 URLSearchParams 객체를 통해 처리했으며, 필요에 따라 set, delete 등의 메서드로 값을 갱신하도록 구현했다.
 

const updateQueryParams = (newParams: Record<string, any>) => {
  const params = new URLSearchParams(window.location.search);

  Object.entries(newParams).forEach(([key, value]) => {
    if (Array.isArray(value)) {
      value.length > 0 ? params.set(key, value.join(',')) : params.delete(key);
    } else {
      value ? params.set(key, String(value)) : params.delete(key);
    }
  });

  router.push(`/checker?${params.toString()}`, { scroll: false });
};

 

2. URL에서 필터 상태를 초기화하는 로직

페이지 진입 시 searchParams에서 각 필터 값을 읽어들여 클라이언트 상태를 구성했다.

const filterState = useMemo(() => ({
  status: searchParams.get('status')?.split(',') || [],
  search: searchParams.get('search') || '',
  reference_ids: searchParams.get('reference_ids')?.split(',').map(Number) || [],
}), [searchParams]);

 

3. 서버 사이드 렌더링과의 통합

초기 데이터 로딩 시 getServerSideProps를 활용하여 URL 쿼리로부터 필터와 페이지네이션 정보를 추출하고 서버에서 데이터를 미리 가져왔다.
 

export const getServerSideProps = async (context) => {
  const query = context.query;

  const filter = {
    status: query.status?.split(',') || [],
    search: query.search || '',
  };

  const pagination = {
    page: Number(query.page) || 1,
    page_count: Number(query.page_count) || 50,
  };

  const data = await getCheckers(pagination, filter);

  return { props: { data } };
};

 

4. React Query와의 통합

React Query에서는 queryKey에 필터와 페이지 정보를 함께 포함시켜, URL이 바뀌면 자동으로 데이터를 refetch하도록 구성했다.

const { data } = useQuery({
  queryKey: ['checkers', filterState, pagination],
  queryFn: () => getCheckers(pagination, filterState),
  initialData: props.data,
});

 
 

🎯 결과

이처럼 각 상태(필터, 검색, 페이지네이션)를 URL과 직접 연결함으로써 다음과 같은 결과를 얻을 수 있었다.

• 페이지 새로고침 시에도 사용자가 설정한 필터 상태가 유지되었다.
• 필터링된 목록을 그대로 URL로 공유하거나 저장할 수 있게 되었다.
• 브라우저 뒤로가기/앞으로가기 동작이 기대한 대로 작동해 UX가 자연스러워졌다.
• SSR과 React Query 초기 데이터 세팅이 통합되어, 첫 페이지 진입 속도도 빨라졌다.

---

🔁 회고 및 개선 여지

이번 구조 설계를 통해 클라이언트-서버 간 상태 일관성과 공유 가능성이라는 두 마리 토끼를 모두 잡을 수 있었다.
다만 향후 필터 항목이 많아질 경우, 쿼리 문자열이 길어지는 문제가 발생할 수 있어 파라미터 압축 등을 고려할 계획이다.