React Query

// ❌ 기존 방식 - 매번 직접 관리해야 할 것들 const [data, setData] = useState(null) const [isLoading, setIsLoading] = useState(false) const [error, setError] = useState(null) useEffect(() => { setIsLoading(true) fetch('/api/boards') .then(res => res.json()) .then(data => { setData(data); setIsLoading(false) }) .catch(err => { setError(err); setIsLoading(false) }) }, [])

// ✅ React Query - 캐싱, 로딩, 에러, 리패치 자동 처리 const { data, isLoading, isError } = useQuery({ queryKey: ['boards'], queryFn: () => fetch('/api/boards').then(res => res.json()), })

npm install @tanstack/react-query @tanstack/react-query-devtools

import { QueryClient } from '@tanstack/react-query' const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 1, // 네트워크 실패 시 재시도 횟수 (기본값: 3) staleTime: 1000 * 30, // 데이터를 "신선"하다고 보는 시간(ms) (기본값: 0) }, }, })

// src/main.jsx const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 1, // 기본 3회 → 1회로 줄여 빠른 에러 감지 staleTime: 1000 * 30, // 30초간 캐시 유효 (게시판 특성상 자주 바뀌지 않음) }, }, })

// src/main.jsx import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { ReactQueryDevtools } from '@tanstack/react-query-devtools' const queryClient = new QueryClient({ /* 설정 */ }) createRoot(document.getElementById('root')).render( <StrictMode> <QueryClientProvider client={queryClient}> <App /> <ReactQueryDevtools initialIsOpen={false} /> </QueryClientProvider> </StrictMode> )

<QueryClientProvider client={queryClient}> ← QueryClient를 Context에 등록 <App> <ListPage> <List> useQuery(...) ← Context에서 QueryClient를 꺼내 캐시 조회 </List> </ListPage> </App> </QueryClientProvider>

const { data, isLoading, isError, error } = useQuery({ queryKey: ['고유한 키'], // 캐시 식별자 queryFn: () => fetch(...), // 실제 데이터를 가져오는 함수 })

// 단순 키 - 변하지 않는 데이터 queryKey: ['boards'] // 파라미터 포함 - 페이지마다 다른 캐시 queryKey: ['boards', page, size] // ['boards', 1, 10], ['boards', 2, 10] 각각 별도 캐시 // ID 포함 - 게시글마다 다른 캐시 queryKey: ['board', id] // ['board', 1], ['board', 2] 각각 별도 캐시

// axios를 사용하는 경우 - .then()으로 실제 데이터만 추출 queryFn: () => boardsApi.list(page, size).then((res) => res.data) // fetch를 사용하는 경우 queryFn: () => fetch('/api/boards').then(res => res.json()) // async/await 방식 queryFn: async () => { const res = await boardsApi.list(page, size) return res.data }

const { data, // queryFn이 반환한 데이터 (초기에는 undefined) isLoading, // 처음 로딩 중 (데이터 없고 fetch 중) isFetching, // 백그라운드 포함 모든 fetch 중 isError, // 에러 발생 여부 error, // 에러 객체 isSuccess, // 성공 여부 refetch, // 수동으로 다시 가져오기 status, // 'pending' | 'error' | 'success' } = useQuery({ queryKey, queryFn })

useQuery({ queryKey: ['boards', page], queryFn: () => boardsApi.list(page), enabled: !!id, // false면 쿼리 실행 안 함 (조건부 실행) staleTime: 1000 * 60, // 1분간 신선 (전역 설정 오버라이드) placeholderData: (prev) => prev, // 키 변경 시 이전 데이터를 임시로 표시 select: (data) => data.list, // 반환 데이터 변환/선택 retry: false, // 실패 시 재시도 안 함 })

// id가 있을 때만 요청 (useBoard.js) const { data } = useQuery({ queryKey: ['board', id], queryFn: () => boardsApi.select(id).then(res => res.data), enabled: !!id, // id가 undefined/null이면 요청 안 함 })

// useBoards.js - 페이지 이동 시 이전 목록을 유지해 화면 깜빡임 방지 useQuery({ queryKey: ['boards', page, size], queryFn: () => boardsApi.list(page, size).then(res => res.data), placeholderData: (previousData) => previousData, // ↑ 새 데이터 도착 전까지 이전 페이지 데이터를 임시 표시 })

const mutation = useMutation({ mutationFn: (변수) => 서버요청함수(변수), onSuccess: (data) => { /* 성공 후 처리 */ }, onError: (error) => { /* 실패 후 처리 */ }, }) // 호출 mutation.mutate(전달할값)

// 단순 인자 mutationFn: (id) => boardsApi.remove(id) // 객체 인자 (여러 값 전달) mutationFn: ({ data, headers }) => boardsApi.insert(data, headers) // 배열 인자 mutationFn: (idList) => filesApi.removeFiles(idList)

useMutation({ mutationFn: (data) => boardsApi.insert(data), onSuccess: (responseData, variables, context) => { // 요청 성공 시 호출 // responseData: 서버 응답값 // variables: mutate()에 전달한 값 }, onError: (error, variables, context) => { // 요청 실패 시 호출 console.error(error.message) }, onSettled: (data, error, variables) => { // 성공/실패 무관하게 항상 호출 (finally와 유사) }, onMutate: async (variables) => { // 요청 직전에 호출 (낙관적 업데이트에 활용) }, })

const { mutate, // 뮤테이션 실행 함수 (비동기 결과 무시) mutateAsync, // 뮤테이션 실행 함수 (Promise 반환, await 가능) isPending, // 요청 진행 중 isSuccess, // 요청 성공 isError, // 요청 실패 error, // 에러 객체 data, // 성공 응답 데이터 reset, // 상태 초기화 } = useMutation({ mutationFn })

// mutate - fire-and-forget, 에러는 onError로 처리 mutation.mutate(data) // mutateAsync - Promise 반환, try/catch 가능 try { const result = await mutation.mutateAsync(data) console.log(result) } catch (error) { console.error(error) }

// 저장 중 버튼 비활성화 (useBoardMutations.js) return { insertBoard: (data, headers) => insertMutation.mutate({ data, headers }), isInserting: insertMutation.isPending, // 요청 중이면 true } // 컴포넌트에서 <button type="submit" disabled={isInserting}> {isInserting ? '저장 중...' : '저장'} </button>

import { useQueryClient } from '@tanstack/react-query' const queryClient = useQueryClient()

// 특정 키 무효화 queryClient.invalidateQueries({ queryKey: ['boards'] }) // 특정 키 + 파라미터 무효화 queryClient.invalidateQueries({ queryKey: ['board', id] }) // 'boards'로 시작하는 모든 캐시 무효화 (부분 매칭) queryClient.invalidateQueries({ queryKey: ['boards'] }) // → ['boards'], ['boards', 1, 10], ['boards', 2, 10] 모두 무효화

// 현재 캐시 읽기 (서버 요청 없음) const boards = queryClient.getQueryData(['boards', 1, 10]) // 캐시 직접 업데이트 (서버 요청 없이 UI 즉시 반영 - 낙관적 업데이트) queryClient.setQueryData(['board', id], (oldData) => ({ ...oldData, board: { ...oldData.board, title: newTitle } }))

// 다음 페이지를 미리 가져와 캐시에 저장 await queryClient.prefetchQuery({ queryKey: ['boards', nextPage], queryFn: () => boardsApi.list(nextPage).then(res => res.data), })

// useBoardMutations.js const queryClient = useQueryClient() // 글 등록 성공 → 목록 캐시 무효화 onSuccess: async () => { queryClient.invalidateQueries({ queryKey: ['boards'] }) // → 목록 페이지 재진입 시 최신 목록 로드 } // 글 수정 성공 → 목록 + 단건 캐시 무효화 onSuccess: async () => { queryClient.invalidateQueries({ queryKey: ['boards'] }) // 목록 queryClient.invalidateQueries({ queryKey: ['board', id] }) // 상세 } // 파일 삭제 성공 → 해당 게시글 캐시 무효화 onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['board', id] }) // → 파일 목록이 즉시 갱신됨 }

// src/main.jsx import { ReactQueryDevtools } from '@tanstack/react-query-devtools' <QueryClientProvider client={queryClient}> <App /> <ReactQueryDevtools initialIsOpen={false} /> {/* ↑ 화면 우하단에 플로팅 버튼으로 표시 */} </QueryClientProvider>

컴포넌트 마운트 │ ▼ 캐시에 데이터 있음? ├─ 없음 ──► 서버 요청 → 데이터 저장 → isLoading: true 동안 로딩 표시 │ └─ 있음 │ ├─ fresh? (staleTime 이내) │ └─ 캐시 즉시 반환 (서버 요청 안 함) │ └─ stale? (staleTime 초과) └─ 캐시 즉시 반환 + 백그라운드에서 서버 재요청 (isFetching: true) │ └─ 새 데이터 도착 → 캐시 교체 → UI 갱신

데이터 도착 │ ├── staleTime 이내 → "fresh" (재요청 안 함) │ └── staleTime 초과 → "stale" (다음 접근 시 백그라운드 재요청) 컴포넌트 언마운트 │ └── gcTime 이내 → 캐시 유지 (다시 마운트 시 즉시 사용) gcTime 초과 → 캐시 삭제 (다시 마운트 시 새 요청)

main.jsx QueryClient (retry: 1, staleTime: 30s) QueryClientProvider App └─ 각 페이지 → 컴포넌트 → 커스텀 훅 ├─ useBoards(page, size) → useQuery(['boards', page, size]) ├─ useBoard(id) → useQuery(['board', id]) └─ useBoardMutations(id) → useMutation + useQueryClient

ListPage 마운트 └─ useBoards(1, 10) 호출 └─ useQuery({ queryKey: ['boards', 1, 10], ... }) ├─ 캐시 없음 → boardsApi.list(1, 10) 호출 → GET /api/boards?page=1&size=10 │ isLoading: true → 로딩 표시 │ 응답 도착 → 캐시 저장 → UI 표시 │ └─ 캐시 있음 (30초 이내) → 즉시 반환, 서버 요청 없음

Insert 컴포넌트 └─ onSubmit → insertBoard(formData) 호출 └─ insertMutation.mutate({ data: formData, headers }) └─ boardsApi.insert() → POST /api/boards └─ onSuccess: ├─ queryClient.invalidateQueries(['boards']) │ ↓ │ ['boards', 1, 10] 캐시 "만료"로 표시 │ ├─ Swal 성공 알림 └─ navigate('/boards') ↓ ListPage 마운트 └─ useBoards() 재실행 └─ 캐시 만료 → 서버 재요청 → 최신 목록 표시

❌ 컴포넌트 안에 직접 작성 List.jsx → useQuery 로직 포함 Update.jsx → useMutation 로직 포함 → 로직이 컴포넌트에 섞여 재사용 불가 ✅ 커스텀 훅으로 분리 useBoards.js → 목록 조회 로직 캡슐화 useBoard.js → 단건 조회 로직 캡슐화 useBoardMutations.js → CRUD 로직 캡슐화 → 여러 컴포넌트에서 재사용 가능 → 테스트 용이 → 컴포넌트는 UI에만 집중

// useBoards.js export const useBoards = (page = 1, size = 10) => { const { data, isLoading, isError } = useQuery({ queryKey: ['boards', page, size], // 페이지마다 별도 캐시 queryFn: () => boardsApi.list(page, size).then(res => res.data), placeholderData: (prev) => prev, // 페이지 이동 시 이전 데이터 유지 }) return { list: data?.list ?? [], pagination: data?.pagination ?? {}, isLoading, isError } } // useBoard.js export const useBoard = (id) => { const { data, isLoading, isError, refetch } = useQuery({ queryKey: ['board', id], // id마다 별도 캐시 queryFn: () => boardsApi.select(id).then(res => res.data), enabled: !!id, // id 없으면 요청 안 함 }) return { board: data?.board ?? null, fileList: data?.fileList ?? [], isLoading, isError, refetch } } // useBoardMutations.js export const useBoardMutations = (id) => { const queryClient = useQueryClient() const insertMutation = useMutation({ mutationFn: ({ data, headers }) => boardsApi.insert(data, headers), onSuccess: async () => { queryClient.invalidateQueries({ queryKey: ['boards'] }) // 목록 갱신 await successAlert('등록 성공', '게시글 등록이 완료되었습니다.') navigate('/boards') }, }) return { insertBoard: (data, headers) => insertMutation.mutate({ data, headers }), isInserting: insertMutation.isPending, } }

@tanstack/react-query ├─ QueryClient → 캐시 저장소, 전역 설정 ├─ QueryClientProvider → Context로 앱 전체에 공급 ├─ useQuery → 데이터 읽기 (GET) │ ├─ queryKey → 캐시 식별자 (배열) │ ├─ queryFn → 서버 요청 함수 │ ├─ enabled → 조건부 실행 │ └─ placeholderData → 이전 데이터 임시 표시 ├─ useMutation → 데이터 쓰기 (POST/PUT/DELETE) │ ├─ mutationFn → 서버 요청 함수 │ ├─ onSuccess → 성공 콜백 │ ├─ onError → 실패 콜백 │ └─ isPending → 요청 진행 중 여부 ├─ useQueryClient → QueryClient 인스턴스 접근 │ ├─ invalidateQueries → 캐시 무효화 (가장 자주 사용) │ ├─ setQueryData → 캐시 직접 수정 │ └─ getQueryData → 캐시 읽기 └─ ReactQueryDevtools → 개발용 캐시 상태 시각화