React Query 쿼리키 구조화하기

1. 쿼리키 구조화의 필요성

React Query를 사용하다 보면 여러 API 요청을 관리하게 되는데, 이때 쿼리키를 체계적으로 관리하는 것이 중요합니다. 잘 구조화된 쿼리키는 다음과 같은 이점이 있습니다.

• 쿼리키의 일관성 유지
• 캐시 관리의 용이성
• 코드의 가독성 향상
• 타입 안정성 확보

2. 쿼리키 구조화 방법

2.1 기본 구조

file directory src/app/constant/queryKey/dummy.ts

export const QUERY_KEYS = {
  POST: {
    LIST: ["post", "list"],
    DETAIL: (id: number) => ["post", "detail", id],
    CREATE: ["post", "create"],
    UPDATE: (id: number) => ["post", "update", id],
    DELETE: (id: number) => ["post", "delete", id],
  },
  COMMENT: {
    LIST: (postId: number) => ["comment", "list", postId],
    DETAIL: (id: number) => ["comment", "detail", id],
    CREATE: ["comment", "create"],
    UPDATE: (id: number) => ["comment", "update", id],
    DELETE: (id: number) => ["comment", "delete", id],
  },
  USER: {
    LIST: ["user", "list"],
    DETAIL: (id: number) => ["user", "detail", id],
    PROFILE: ["user", "profile"],
    PLANS: {
      INDEX: ["plans", "user"],
      SCRAP: ["plans", "user", "scrap"],
    },
  },
} as const;

2.2. 구조화 원칙

• 계층적 구조: 도메인별로 계층 구조를 만들어 관리
• CRUD 분리: 생성(Create), 조회(Read), 수정(Update), 삭제(Delete) 작업별로 구분
• 동적 파라미터: ID나 필터와 같은 동적 값은 함수로 처리
• 타입 안정성: as const를 사용하여 타입 안정성 확보

3. 실제 사용 예시

3.1 쿼리 훅 사용

// 게시글 목록 조회
export const usePostList = (options?: UseQueryOptions<Post[]>) => {
  return useQuery({
    queryKey: QUERY_KEYS.POST.LIST,
    queryFn: () => customFetch<never, Post[]>(`/posts`),
    ...options,
  });
};

// 게시글 상세 조회
export const usePostDetail = (id: number, options?: UseQueryOptions<Post>) => {
  return useQuery({
    queryKey: QUERY_KEYS.POST.DETAIL(id),
    queryFn: () => customFetch<never, Post>(`/posts/${id}`),
    ...options,
  });
};

3.2 뮤테이션 훅 사용

// 게시글 생성
export const useCreatePost = (options?: UseMutationOptions<Post, Error, Partial<Post>>) => {
  return useMutation({
    mutationKey: QUERY_KEYS.POST.CREATE,
    mutationFn: (data: Partial<Post>) =>
      customFetch<Partial<Post>, Post>(`/posts`, {
        method: "POST",
        data: data,
      }),
    ...options,
  });
};

4. 캐시 무효화

쿼리키 구조화를 통해 캐시 무효화도 더 쉽게 관리할 수 있습니다.

// 게시글 생성 후 목록 캐시 무효화
export const useCreatePost = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (newPost: Omit<Post, "id">) =>
      customFetch<Omit<Post, "id">, Post>("/posts", {
        method: "POST",
        data: newPost,
      }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: QUERY_KEYS.POST.LIST });
    },
  });
};

5. 캐시 무효화

React Query의 쿼리키를 체계적으로 구조화하면 다음과 같은 이점을 얻을 수 있습니다.

1. 코드의 일관성과 가독성 향상
2. 캐시 관리의 용이성
3. 타입 안정성 확보
4. 유지보수성 향상

이러한 구조화된 쿼리키 관리는 대규모 애플리케이션에서 특히 유용하며, 팀 프로젝트에서도 일관된 코드 스타일을 유지하는 데 도움이 됩니다.