OpenAPI 스펙에서 TanStack Query 훅을 자동생성

• 엔드포인트가 수백 개인 SaaS의 데이터 페칭 계층

증상

• 엔드포인트마다 데이터 페칭 훅을 손으로 반복 작성 — 양이 많고 실수가 섞임
• queryKey 오타·불일치로 무효화가 엉뚱한 키를 지워 캐시가 갱신되지 않음
• 서버가 필드를 바꿔도 프론트는 런타임에서야 알게 됨

원인

• 서버 OpenAPI 스펙이 이미 단일 진실원인데, 프론트가 그것과 무관하게 훅과 키를 따로 손으로 씀
• 두 곳이 같은 계약을 각자 표현하니 어긋나도 아무도 모름

조치

• 스펙에서 엔드포인트별 훅을 생성 — 조회 계열은 useQuery, 변경 계열은 useMutation
• 각 훅에 대응하는 queryKey 팩토리도 함께 생성해 무효화 시 같은 팩토리를 재사용. 손으로 키를 짜지 않으니 불일치가 생길 자리가 없어짐
• 타입 안전 fetch 클라이언트를 베이스로 깔고 그 위에 훅을 얹음
• 생성물은 커밋해서 관리하는 코드가 아니라 재생성 산출물 — 스펙이 바뀌면 다시 뽑음
• 생성 코드는 방대해서 아무 데서나 직접 import하면 결합이 퍼짐 → 도메인별 재export 지점을 통해서만 쓰게 강제

결과

• 경로·파라미터·요청/응답이 스펙 타입에 묶여, 서버가 필드를 바꾸면 빌드에서 실패로 잡힘
• 캐시 무효화가 정확히 대상만 지움

이 경계 강제는 린트로 → FSD import 경계를 린터로 강제