[React-Query] Query Key 관리와 개선 경험

React Query를 도입하면서 또 하나의 중요한 고민은 queryKey 관리였습니다. 여러 파일에 걸쳐 queryKey를 관리하다 보니 재사용성과 유지보수 측면에서 어려움을 겪었는데요, 이를 해결하기 위한 전략을 공유하고자 합니다.

 

Query Key 중앙 관리 시스템 도입

여러 파일에 분산된 queryKey를 하나의 모듈로 통합 관리하는 방식을 도입했습니다.

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

 

이렇게 중앙화된 관리 방식을 통해:

• 중복 코드 제거
• 키 재사용성 향상
• 타입 안정성 확보
• 유지보수 용이성 증가

Mutation과 Query Key 연동 최적화

캐시 무효화(invalidation) 로직을 더 효율적으로 관리하기 위해 Tanstack Query의 setMutationDefaults를 활용했습니다.

// mutations/planMutations.ts
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 })
  },
})

 

이를 통해 컴포넌트에서는 순수하게 UI 관련 로직에만 집중할 수 있게 되었습니다:

// components/PlanCreator.tsx
mutation.mutate(newTodo, {
    onSuccess() {
        setState(newState);
        router.push('/plans');
    }
});

 

이러한 분리를 통해 얻은 장점들:

• 관심사의 명확한 분리
• 캐시 무효화 로직의 중앙화
• 코드 재사용성 향상
• 유지보수 용이성 증가

향후 개선 계획

현재는 자체적인 모듈화 방식을 사용하고 있지만, 추후에는 query-key-factory 라이브러리 도입을 고려하고 있습니다. 이 라이브러리는 더 강력한 타입 안정성과 편리한 키 관리 기능을 제공하여, 현재 시스템을 한 단계 더 발전시킬 수 있을 것으로 기대됩니다.

결론

Query Key 관리는 React Query를 사용할 때 간과하기 쉽지만 매우 중요한 부분입니다. 중앙화된 관리 시스템과 setMutationDefaults를 활용한 캐시 무효화 전략을 통해, 더 유지보수하기 쉽고 안정적인 코드베이스를 구축할 수 있었습니다.