TanStack Query v4→v5 이관 — 204 무한 루프·queryKey 무효화 전역 대응

• 데이터 페칭이 많은 SaaS의 서버 상태 관리를 v4 → v5로 메이저 이관
• 신규 앱을 최신 프레임워크로 올리려면 React 19가 필요했고, v4는 React 19 미지원이라 이관이 전제 조건이었음

증상

이관 도중 드러난 두 회귀. 개별 화면 버그가 아니라 앱 전역 쿼리에 걸림.

• 204 응답에서 무한 렌더 루프 — 빈 본문을 파싱하면 결과가 undefined인데, v5는 queryFn의 undefined 반환을 금지하고 "아직 데이터 없음"으로 간주해 재시도·리렌더를 반복
• 캐시 무효화가 빗나감 — v4식 키로 invalidateQueries하면 대상 쿼리를 못 잡거나 과도하게 잡음

원인

• v5가 queryKey를 배열로 강제하고 매칭 규칙을 엄격하게 바꿈 — 기존 키 구조가 그 규칙에 맞지 않았음
• 두 건 모두 앱 전역에 깔린 규칙 변경이라 화면 단위 수정으로는 닫히지 않음

조치

• 204일 때 undefined 대신 null을 반환해 "정상적으로 빈 값"임을 알림
• 키 구조를 v5 규칙에 맞춰 전역 통일 → 무효화 대상이 정확히 일치
• 재요청·stale·retry 정책을 클라이언트 기본 옵션으로 한 번에 지정 — 개별 쿼리에 흩어진 설정을 줄여 이관 후 동작을 예측 가능하게

이관 방식

• 공식 가이드의 breaking change를 전수 정리하고 앱에서 실제로 쓰는 API만 추려 영향 목록을 만듦
• 목록을 기준으로 앱별·도메인별로 나눠 단계마다 동작을 확인하며 진행 — 한 번에 올리면 회귀 지점을 특정할 수 없음

이 서버 상태 훅을 스펙에서 자동생성하는 쪽 → OpenAPI → TanStack Query 훅 자동생성