اگر با React کار میکنید، احتمالاً بارها بین fetch، Axios، ky یا HTTP Clientهای دیگر انتخاب کردهاید.
اما وقتی TanStack Query وارد معماری پروژه میشود، یک سؤال مهمتر مطرح میشود:
آیا HTTP Client ما واقعاً با مدل کاری TanStack Query هماهنگ است؟
همین سؤال یکی از دلایلی بود که من tanstack-fetch را ساختم.
هدف tanstack-fetch این نیست که صرفاً یک HTTP Client دیگر باشد.
ایده اصلی این است:
TanStack Query مسئول Server State باشد و tanstack-fetch مسئول HTTP Transport.
TanStack Query برای queryFn یک مدل بسیار ساده دارد.
queryFn باید:
داده را برگرداند
در صورت خطا exception ایجاد کند
از AbortSignal پشتیبانی کند
مثلاً با Fetch خام:
useQuery({ queryKey: ['users'], queryFn: ({ signal }) => fetch('/api/users', { signal }).then(res => res.json()), })
در پروژه واقعی، اما HTTP Client معمولاً مسئولیتهای بیشتری پیدا میکند:
Authentication
Token Refresh
Interceptor
Error Handling
SSR
SSE
Retry
Type Safety
Request Cancellation
اینجاست که Axios یا ky وارد میشوند.
استفاده از Axios در TanStack Query کاملاً ممکن است:
queryFn: async ({ signal }) => { const { data } = await axios.get<User[]>('/users', { signal, }) return data }
اما یک تبدیل اضافه داریم:
Axios Response ↓ response.data ↓ TanStack Query
این تبدیل کوچک بهتنهایی مشکل بزرگی نیست.
اما در یک پروژه بزرگ، ممکن است صدها بار تکرار شود.
ky نسبت به Axios سبکتر و نزدیکتر به Fetch است:
queryFn: ({ signal }) => ky.get('/users', { signal }).json<User[]>()
اما همچنان باید Response را به داده تبدیل کنیم:
Fetch Response ↓ .json() ↓ TanStack Query
این API کاملاً قابل قبول است و ky برای بسیاری از پروژهها انتخاب خوبی است.
اما اگر TanStack Query بخش اصلی Server State پروژه باشد، میتوان سؤال دیگری مطرح کرد:
آیا میتوان HTTP Client را مستقیماً با مدل TanStack Query هماهنگ کرد؟
ایده tanstack-fetch دقیقاً همین است.
مثلاً:
const api = createFetch({ baseUrl: 'https://api.example.com', })
و بعد:
useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get<User[]>('/users', { signal }), })
نتیجه مستقیماً داده است:
User[]
بنابراین خبری از این موارد نیست:
response.data
یا:
response.json()
خطاهای HTTP نیز از طریق FetchError مدیریت میشوند.
هدف این نیست که tanstack-fetch جای TanStack Query را بگیرد.
برعکس، هر کدام مسئولیت مشخص خودشان را دارند:
┌─────────────────────────┐ │ React UI │ ├─────────────────────────┤ │ TanStack Query │ │ │ │ Server State │ │ Cache │ │ Retry │ │ Refetch │ │ Mutations │ ├─────────────────────────┤ │ tanstack-fetch │ │ │ │ HTTP Transport │ │ Type Safety │ │ Authentication │ │ Token Refresh │ │ Interceptors │ │ SSE │ ├─────────────────────────┤ │ Fetch │ └─────────────────────────┘
به این شکل، هر لایه یک مسئولیت مشخص دارد.
یکی از مشکلات رایج در اپلیکیشنهای واقعی، Refresh Token است.
فرض کنید چند درخواست تقریباً همزمان با 401 مواجه شوند.
بدون هماهنگی ممکن است اتفاقی شبیه این رخ دهد:
Request A → 401 → refresh Request B → 401 → refresh Request C → 401 → refresh Request D → 401 → refresh
در حالی که چیزی که معمولاً میخواهیم این است:
Request A → 401 ─┐ Request B → 401 ─┤ Request C → 401 ─┼→ یک refresh → retry Request D → 401 ─┘
tanstack-fetch برای این سناریو یک Refresh Token Interceptor با الگوی single-flight دارد.
همچنین امکان Refresh قبل از منقضی شدن Token و Refresh واکنشی بعد از اولین 401 را فراهم میکند.
در اپلیکیشنهای مدرن React، HTTP Request فقط به Browser محدود نیست.
در محیطهایی مثل Next.js ممکن است با مواردی مثل:
SSR
Cookie Forwarding
Server-side Request
Authentication
SSE
Request Cancellation
مواجه شویم.
بنابراین HTTP Client باید بتواند این سناریوها را نیز پوشش دهد.
tanstack-fetch برای مواردی مانند SSR Cookie Forwarding، Authenticated SSE و SSE Resume قابلیتهایی ارائه میکند.
tanstack-fetch:
پشتیبانی و طراحیشده با تمرکز روی TanStack Query
ky:
تمرکز مستقیمی روی TanStack Query ندارد
Axios:
تمرکز مستقیمی روی TanStack Query ندارد
tanstack-fetch:
بله
ky:
بله
Axios:
خیر
tanstack-fetch:
بله، با FetchError
ky:
بله، با HTTPError
Axios:
بله، با AxiosError
tanstack-fetch:
پشتیبانی میکند
ky:
پشتیبانی میکند
Axios:
پشتیبانی میکند
tanstack-fetch:
Built-in
ky:
نیاز به پیادهسازی سفارشی دارد
Axios:
نیاز به پیادهسازی سفارشی دارد
tanstack-fetch:
پشتیبانی میکند
ky:
نیاز به پیادهسازی سفارشی دارد
Axios:
نیاز به پیادهسازی سفارشی دارد
tanstack-fetch:
First-class support
ky:
نیاز به پیادهسازی دستی
Axios:
نیاز به پیادهسازی دستی
tanstack-fetch:
پشتیبانی میکند
ky:
نیاز به پیادهسازی سفارشی دارد
Axios:
نیاز به پیادهسازی سفارشی دارد
tanstack-fetch:
جدید
ky:
بالغ
Axios:
بسیار بالغ
البته این جدول به این معنی نیست که یک کتابخانه برای همه پروژهها مناسبتر است.
هر کدام مسئله متفاوتی را هدف قرار میدهند.
اگر:
از TanStack Query استفاده میکنید
میخواهید queryFn سادهتر شود
Type Safety برایتان مهم است
Token Refresh دارید
با SSR کار میکنید
به SSE نیاز دارید
پروژه جدیدی شروع کردهاید
یا قصد مهاجرت از Axios، ky، ofetch یا Fetch را دارید
tanstack-fetch میتواند گزینهای باشد که ارزش بررسی دارد.
اگر فقط یک Fetch Wrapper سبک و ساده میخواهید و وابستگی خاصی به TanStack Query ندارید، ky میتواند انتخاب مناسبی باشد.
اگر یک پروژه بزرگ با Axios دارید و:
Interceptorهای پیچیده دارید
اکوسیستم بزرگی حول Axios ساختهاید
تیم شما تجربه زیادی با Axios دارد
و هزینه Migration بیشتر از مزایای آن است
دلیلی وجود ندارد صرفاً به خاطر یک معماری جدید همه چیز را Rewrite کنید.
انتخاب HTTP Client جدید معمولاً سختترین قسمت ماجرا نیست.
Migration سختتر است.
در یک پروژه واقعی ممکن است این موارد همزمان وجود داشته باشند:
axios.get(...) axios.post(...) fetch(...) ky.get(...)
در صدها فایل مختلف.
به همین دلیل tanstack-fetch یک Migration CLI نیز دارد.
این CLI میتواند به شناسایی HTTP Call Siteهای موجود کمک کند و مسیر مهاجرت از:
Axios ky ofetch Fetch
به معماری سازگارتر با TanStack Query را سادهتر کند.
هدف این نیست که کل پروژه را یکباره Rewrite کنید.
هدف، Incremental Migration است.
لزوماً نه.
اگر پروژه شما با Axios بهخوبی کار میکند، احتمالاً نیازی به Rewrite کردن آن ندارید.
سؤال جالبتر این است:
وقتی TanStack Query مرکز Server State پروژه ماست، چرا HTTP Client باید باعث شود در هر
queryFnیک لایه Adapter اضافی داشته باشیم؟
tanstack-fetch دقیقاً برای پاسخ دادن به همین سؤال ساخته شده است.
Axios یک HTTP Client بسیار بالغ و قدرتمند است.
ky یک Fetch Wrapper سبک و تمیز است.
tanstack-fetch رویکرد متفاوتی دارد:
HTTP Layer را با Mental Model تاناستک Query هماهنگ میکند.
در نتیجه معماری میتواند به شکل زیر باشد:
TanStack Query ↓ Server State tanstack-fetch ↓ HTTP Transport Fetch ↓ Network Primitive
اگر پروژه جدیدی با React و TanStack Query شروع میکنید، این مدل معماری ارزش بررسی دارد.
و اگر پروژه فعلی شما با Axios یا ky نوشته شده، لازم نیست همه چیز را یکباره تغییر دهید.
میتوانید با چند API شروع کنید، چند queryFn را مهاجرت دهید و بعد Developer Experience و هزینه نگهداری را مقایسه کنید.
tanstack-fetch یک پروژه Open Source است و پروژه رسمی TanStack نیست.