TanStack Query · API 경계
TanStack Query snake_case ↔ camelCase
TanStack Query cache에는 앱이 실제 사용하는 camelCase shape를 저장하세요. queryFn과 mutationFn 경계에서 naming을 정규화합니다.
query function에서 camelCase 데이터 반환
import { useQuery } from "@tanstack/react-query"
import { apiJson } from "./api"
type UserProfile = {
userId: number
firstName: string
}
export function useUserProfile(userId: number) {
return useQuery({
queryKey: ["user-profile", userId],
queryFn: () => apiJson<UserProfile>(`/users/${userId}`),
})
}queryFn이 정규화된 데이터를 반환하면 같은 query key를 읽는 모든 component가 동일한 shape를 사용합니다.
request 경계에서 mutation 변수 변환
import { useMutation, useQueryClient } from "@tanstack/react-query"
import { apiJson } from "./api"
type UpdateUser = {
firstName: string
}
export function useUpdateUser(userId: number) {
const queryClient = useQueryClient()
return useMutation({
mutationFn: (input: UpdateUser) =>
apiJson(`/users/${userId}`, {
method: "PATCH",
body: input,
}),
onSuccess: (data) => {
queryClient.setQueryData(["user-profile", userId], data)
},
})
}앱 입력은 camelCase type으로 유지하고 request 함수 안에서 server의 snake_case contract로 변환합니다.
프로덕션 고려사항
- TanStack Query v5의 useQuery와 useMutation은 단일 options-object 형태를 사용합니다.
- 같은 query key에 raw snake_case와 camelCase를 섞지 말고 하나의 canonical shape만 cache하세요.
- mutation 응답을 cache에 쓰기 전에 정규화하세요.
- case 변환은 transport concern이며 React component는 이미 정규화된 데이터를 사용해야 합니다.
JSON 경계 온라인 테스트
중첩 객체, 배열, 제외 키, stop path, 접두사, 충돌, key-only diff를 구현 전에 확인하세요.
.json 파일을 놓거나 기기에서 선택
파일은 브라우저에서만 읽습니다. 최대 크기: 5 MB.
변환된 JSON
{
"userProfile": {
"firstName": "Ada",
"createdAt": "2026-09-12"
}
}파싱, 파일 읽기, 포맷 및 키 변환은 모두 브라우저에서 로컬로 실행됩니다. JSON 입력은 변환 서버로 전송되지 않습니다.