useQuery의 queryKey를 어떤 방식으로 관리하시나요?

[Kimbangg]

고민

• 문제 상황

  • 신규 서비스를 개발하는 과정에서, API 응답이 스펙과 다르다는 걸 발견했어요. 이상해서 서버 개발자 분께 말씀드렸고, Swagger를 통해 함께 응답 값을 확인해보니 스펙에 맞는 데이터가 잘 내려오고 있더라고요. 원인을 살펴보니, 비슷한 코드를 복사해오는 과정에서 queryKey까지 그대로 복사되어서 캐싱된 잘못된 응답 값을 가져온 게 문제였어요.

• 궁금한 점

  • Q1. 쿼리 키를 관리하는 방법들이 있으신가요?
  • Q2. 중복된 쿼리 키를 입력 했을 때, 이를 검사해주는 툴이나 컨벤션이 있을까요?

코드

export const userQueries = {
  ageQueryKey: () => ['age'],
  age: () => {
    return queryOptions({
      queryKey: userQueries.ageQueryKey(),
      queryFn: async () => await fetchUserAge(),
    });
  },
  contactQueryKey: () => ['contact'],
  contact: () => {

    return queryOptions({
      // PROBLEM: age와 동일한 키를 사용
      queryKey: userQueries.ageQueryKey(),
      queryFn: async () => await fetchUserContact(),
    });
  },
};

참고 자료

• 스크린샷:
• 다이어그램:
• 링크 (ex. 피그마, 노션 등):

[jhlee0409]

저의 경우
/~https://github.com/lukemorales/query-key-factory 라이브러리를 사용해서 관리하고 있는데요.
queryKeys를 관리하는 특정 도메인을 모체로 하는 객체를 만들고 하위의 all, list, detail 등 세부적인 API에 따라 나눈 후 사용하고 있습니다.

특정 도메인을 나타내기 위한 상수값만 관리를 하면 되기도 하구요
inferQueryKeyStore 메소드를 통해 특정 쿼리의 타입을 추출하여 타입 체크도 가능합니다!!

[Kimbangg]

쿼리 키 관리를 지원하는 라이브러리도 있군요 👍
제품이 커지면서 쿼리 키를 관리하는 것도 꽤나 번거롭게 느껴졌는데, 도메인 단위로 분리해서 관리해보겠습니다 :)

[jhlee0409]

저도 처음에는 쿼리 키 관리에 대해 고민이 많았었는데요
우연치 않게 v4 docs에서 해당 라이브러리에 대한 언급이 있어서 그 떄부터 사용했던거 같네요

https://tanstack.com/query/v4/docs/framework/react/community/lukemorales-query-key-factory

[jihostudy]

저도 queryKey 값을 토대로 캐싱하고, revalidate 하는 과정에서 여러 파일들을 오가는 과정이 너무 번거로웠어요.
그래서, 특별하진 않지만 하나의 모듈(파일)에 queryKey를 모두 모아서 관리하면 중복된 값을 줄일 수 있겠다고 생각했어요.
(mutationKey도 같이 모듈화하여 사용하였어요.)

(이런 식으로요!)

export const QUERY_KEYS = {
  GENERAL: {
    PLANS: {
      INDEX: ['plans'],
    },
    PLAN: {
      INDEX: (planId: number) => ['plan', planId],
    },
    PLACES: {
      INDEX: ['places'],
    },
    PLACE: {
      INDEX: ['place']
    },
  },
}

또한, 캐싱된 값은 mutation을 하면서 재평가하는 경우가 많다는 점을 토대로, 각각의 mutation 이 재평가하는 qeuryKey를 미리 지정하면 좋겠다고 생각했어요.

그래서, Tanstack Query에서 제공하는 setMutationDefaults를 사용했어요. setMutationDefaults를 사용하면 mutation 시 수행할 일을 미리 정의할 수 있어요.

따라서, 각 mutation이 고정으로 사용하는 모듈 파일에는 캐싱 키관리를 하고, 컴포넌트에서는 각각의 상황에 맞는 UI 관련 로직을 수행하도록 분리했어요.

1. setMutationDefaults로 키 관리

queryClient.setMutationDefaults(MUTATION_KEYS.PLAN.CREATE.key, {
  mutationFn: MUTATION_KEYS.PLAN.CREATE.fc,
  onSuccess(data, variables, context) {
    queryClient.invalidateQueries({ queryKey: QUERY_KEYS.USER.PLANS.INDEX })
  },
})   

2. 실제 컴포넌트에서의 UI 로직

mutation.mutate(newTodo, {
    onSuccess() {
        setState(어떤 값으로 바꾼다)
        router.push(어디로 이동한다)
    }
});

이렇게 사용하니, mutation 하면서 여러 파일을 돌아다니며 재평가하는 queryKey를 찾지 않고, Key 관리와 UI 로직을 분리할 수 있어서 좋았어요.

참고 (블로그)

[ayden94]

저는 Axios.instance ➠ class Fetcher ➠ class Request ➠ useAdaptor ➠ Component의 흐름으로 각각의 데이터 처리 과정을 추상화해서 쓰고 있습니다. 이 중에서 쿼리 키 관리는 class Request 의 책임으로 두고 있어요.

export class BookRequest extends Fetcher {
  constructor() {
    super();
  }

  queryKey = ["book"];

  getBookByIsbn(isbn13: string) {
    return {
      queryKey: [...this.queryKey, isbn13],
      queryFn: this.fetcher<Item>(`/aladin/detail?isbn=${isbn13}`),
      enabled: !!isbn13,
    };
  }

  ...
}

만약 도메인이 커질 경우에는 해당 도메인의 메인이 되는 class Request를 컴포지션 하는 식으로 쿼리 키를 넘겨주고 있습니다.

export class ArticleRequest extends Fetcher {
  queryKey: ["article"]

  ...
}

export class ArticleLikeRequest extends Fetcher {
  queryKey: Array<string>

   constructor(queryKey: string) {
      super();
      const articleRequest = new ArticleRequest();
      this.queryKey = [ ...articleRequest.queryKey, "like" ]; // queryKey 확장
    }
  }
  
  checkArticleLike(reportId: string) {
    return {
      queryKey: [...this.queryKey, reportId],
      queryFn: this.fetcher<{ isLiked: boolean }>(`/article/${reportId}/like`),
    };
  }

  ...
}

useAdaptor 훅에서는 각 엔드포인트에 따른 클래스를 호출에서 사용하고 있습니다.

export const useCheckArticleLikeAdaptor(reportId: string) {
  const articleLikeRequest = new ArticleLikeRequest()
  const { data } = useQuery(articleLikeRequest.checkArticleLike(reportId: string))

  …
}

아주 대규모의 프로젝트에서도 이러한 패턴이 유효할지는 잘 모르겠습니다만, 적당한 수준의 프로젝트에서는 아직까지는 꽤 괜찮다고 생각합니다 :)

[aga97]

query options api를 이용해서 query-factory를 만들어서 사용하고 있습니다.

https://tkdodo.eu/blog/the-query-options-api

[clockk]

저도 개인적으로 @lukemorales/query-key-factory를 자주 사용하고있습니다.
다만 queryKey가 아닌 mutationKey의 경우 createMutationKeys라는 메소드가 deprecated 예정으로 되어있어, mutationKey의 경우 직접 만들어 관리하고있습니다.
(+ 현재버전에서 createQueryKey를 반환 받은 queryKey 값을 mutationKey로 사용해도 되긴 합니다 )

[dearlsh94]

별도의 라이브러리를 사용하지는 않았고, tkdodo 블로그에서 제안하는 factory 패턴을 참고해서, 각 기능마다 생성하면서 사용했었던 경험이 있어요.

https://tkdodo.eu/blog/effective-react-query-keys#use-query-key-factories

[joseph0926]

위에서 언급된 npm 패키지는 좋긴한데 간단하게 사용하기에는 약간 복잡하고 마지막 업데이트가 1년이 넘은 상황이라(v5이전) 약간의 이슈도 존재합니다
이슈

---

리액트 쿼리 제작자가 작성한 인강?문서?(query.gg)에도
단순한 쿼리키 팩토리나 약간의 개선만을 언급하고 특별히 복잡한 패턴을 언급하지는 않고있습니다

예시로

const todoKeys = {
  all: () => ['todos'],
  allLists: () => [...todoKeys.all(), 'list'],
  list: (sort) => [...todoKeys.allLists(), { sort }],
}

이런 단순한 객체 형태나
나아가서는

const todoQueries = {
  all: () => ({ queryKey: ['todos'] }),
  allLists: () => ({
    queryKey: [...todoQueries.all().queryKey, 'list']
  }),
  list: (sort) => ({
    queryKey: [...todoQueries.allLists().queryKey, sort],
    queryFn: () => fetchTodos(sort),
    staleTime: 5 * 1000,
  }),
  allDetails: () => ({
    queryKey: [...todoQueries.all().queryKey, 'detail']
  }),
  detail: (id) => ({
    queryKey: [...todoQueries.allDetails().queryKey, id],
    queryFn: () => fetchTodo(id),
    staleTime: 5 * 1000,
  }),
}

쿼리옵션과 결합하는 형태까지만 가이드중이지 뭔가 더 특별하고 복잡한 내용은 언급하지 않기때문에 너무 복잡하게 생각 안하고있습니다

[thyeone]

저도 위에서 많이 언급해주신 Query Factory와 queryOptions를 같이 결합하는 패턴으로 사용하고 있습니다