TanStack Query · API 境界
TanStack Query snake_case ↔ camelCase
TanStack Query の cache にはアプリが実際に使う camelCase 形状を保存し、queryFn/mutationFn の境界で変換します。
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 が同じ形状を利用できます。
mutation 変数を request 境界で変換
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 の型を保ち、request 関数で server の snake_case 契約に変換します。
本番利用時の注意点
- TanStack Query v5 は useQuery / useMutation の単一 options object 形式を使用します。
- 同じ query key に raw snake_case と camelCase を混在させず、1つの canonical shape を cache します。
- mutation response を cache に入れる前に正規化してください。
- case 変換は transport concern とし、React component は正規化済みデータを利用します。
JSON 境界をオンラインでテスト
ネスト、配列、除外キー、stop path、接頭辞、衝突、key-only diff をブラウザで確認できます。
.json ファイルをドロップ、または端末から選択
ファイルはブラウザ内でのみ読み取ります。最大 5 MB。
変換後 JSON
{
"userProfile": {
"firstName": "Ada",
"createdAt": "2026-09-12"
}
}解析、ファイル読み込み、整形、キー変換はすべてブラウザ内で実行されます。JSON 入力は変換サーバーへ送信されません。