TanStack Query · API 邊界
TanStack Query snake_case ↔ camelCase
TanStack Query cache 應保存應用程式實際使用的 camelCase shape，並在 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 都會看到相同 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 function 中再轉為 server 的 snake_case contract。
正式環境注意事項
- TanStack Query v5 的 useQuery 與 useMutation 使用單一 options-object 形式。
- 同一 query key 只快取一種 canonical shape，不要混用 raw snake_case 與 camelCase。
- mutation 回應寫入 cache 前先正規化。
- case 轉換屬於 transport concern；React component 應使用已正規化資料。
線上測試 JSON 邊界
在實作前測試巢狀物件、陣列、排除鍵、stop paths、語意前綴、衝突與 key-only diff。
拖放 .json 檔案，或從裝置選取
檔案只會在瀏覽器中讀取。最大檔案大小：5 MB。
轉換後 JSON
{
"userProfile": {
"firstName": "Ada",
"createdAt": "2026-09-12"
}
}解析、檔案讀取、格式化與鍵名轉換都在瀏覽器本機執行。JSON 不會傳送到轉換伺服器。