[개발 위키] UseQueryOptions에 관하여

UseQueryOptions는 React Query 라이브러리에서 제공하는 제네릭 타입으로, useQuery 훅에 전달하는 옵션 객체의 타입을 정의한다. React Query가 제공하는 다양한 설정(옵션)을 명확히 지정하고, 해당 옵션이 어떤 타입을 기대하는지 TypeScript에서 검증할 수 있도록 해준다.

UseQueryOptions의 역할

UseQueryOptions는 React Query에서 사용하는 옵션 객체의 타입으로, 데이터 가져오기(queryFn), 캐싱(staleTime), 에러 처리(onError) 등 다양한 설정을 정의할 수 있다.

UseQueryOptions의 주요 타입 정의

interface UseQueryOptions<
  TQueryFnData = unknown, // queryFn 함수가 반환하는 데이터 타입
  TError = unknown,       // 쿼리 실패 시 반환되는 에러 타입
  TData = TQueryFnData,   // 사용자가 원하는 형식으로 데이터 변환 시의 타입
  TQueryKey extends QueryKey = QueryKey // 쿼리 키의 타입
> {
  queryKey?: TQueryKey;   // React Query의 고유 키 (캐싱 및 상태 관리)
  queryFn?: QueryFunction<TQueryFnData, TQueryKey>; // 데이터를 가져오는 함수
  staleTime?: number;     // 데이터가 신선한 상태로 유지되는 시간 (ms 단위)
  gcTime?: number;        // 데이터가 캐시에 유지되는 시간 (ms 단위)
  enabled?: boolean;      // 쿼리 실행 여부를 조건부로 설정
  retry?: boolean | number; // 실패 시 재시도 여부 및 횟수
  onSuccess?: (data: TData) => void; // 데이터 가져오기 성공 시 호출
  onError?: (err: TError) => void; // 데이터 가져오기 실패 시 호출
  refetchOnWindowFocus?: boolean | "always"; // 윈도우 포커스 시 재요청 여부
  initialData?: TQueryFnData; // 쿼리 실행 전 초기 데이터
}

속성별 상세 설명

1. queryKey

• 역할 : 쿼리를 고유하게 식별하는 키
• 형식 : 단일 문자열, 배열 또는 객체
• 기능
  • 동일한 queryKey를 가진 요청은 동일한 캐시 데이터를 공유
  • 쿼리 식별 및 상태를 효율적으로 관리

queryKey: ["getUsers", userId, filter]

---

2. queryFn

• 역할 : 데이터를 가져오는 함수
• 형식 : (context: QueryFunctionContext<TQueryKey>) => Promise<TQueryFnData>
• 기능
  • 서버 API 호출, 비동기 작업 등 데이터를 요청하는 로직 정의

queryFn: () => fetch("/api/users").then(res => res.json())

---

3. staleTime

• 역할 : 데이터가 "신선한" 상태로 간주되는 시간
• 형식 : 밀리초 단위의 숫자
• 기본값 : 0 (항상 새로 요청)
• 기능
  • 신선한 상태일 때, 동일한 queryKey로 요청해도 새 데이터를 요청하지 않고 캐시 데이터를 반환

staleTime: 5 * 60 * 1000 // 5분 동안 신선

---

4. gcTime (v5에서 cacheTime으로부터 이름 변경)

• 역할 : 데이터가 사용되지 않을 때 캐시에 유지되는 시간
• 형식 : 밀리초 단위의 숫자
• 기본값 : 5분 (300,000ms)
• 기능
  • 설정한 시간 동안 캐시 데이터가 사용되지 않으면 삭제

gcTime: 10 * 60 * 1000 // 10분 동안 유지

---

5. enabled

• 역할 : 쿼리 실행 여부를 조건부로 설정
• 형식 : boolean
• 기능
  • false로 설정하면 해당 쿼리가 실행되지 않음

enabled: query.length > 0 // 검색어가 있을 때만 실행

---

6. retry

• 역할 : 요청이 실패했을 때 재시도 여부 및 횟수 설정
• 형식 : boolean | number (숫자는 재시도 횟수)
• 기능
  • false로 설정 시 재시도하지 않음

retry: 3 // 최대 3번 재시도
retry: false // 재시도하지 않음

---

7. onSuccess

• 역할 : 데이터 가져오기 성공 시 호출되는 콜백 함수
• 형식 : (data: TData) => void
• 기능
  • 성공적으로 데이터를 가져온 후 추가 작업을 수행

onSuccess: (data) => {
  console.log("Fetched successfully:", data);
}

---

8. onError

• 역할 : 요청 실패 시 호출되는 콜백 함수
• 형식 : (err: TError) => void
• 기능
  • 에러를 처리하거나 사용자에게 알림을 제공

onError: (error) => {
  console.error("Error fetching data:", error);
}

---

9. refetchOnWindowFocus

• 역할 : 브라우저 포커스 시 데이터를 재요청할지 여부 설정
• 형식 : boolean | "always"
• 기본값 : true
• 기능
  • 포커스 시 데이터를 재요청하거나, "always"로 설정하면 항상 재요청

refetchOnWindowFocus: false // 포커스 시 재요청하지 않음

---

10. initialData

• 역할 : 쿼리를 실행하기 전에 사용할 초기 데이터
• 형식 : TQueryFnData
• 기능
  • 서버에서 데이터를 가져오기 전에 기본값을 제공

initialData: { items: [] } // 기본 데이터 설정