دمج tRPC مع React Query والمصادقة

سياق tRPC هو كائن يُنشأ حديثًا لكل طلب بواسطة الدالة createTRPCContext. ويمكن أن يتضمن عميل قاعدة البيانات، وجلسة المصادقة، وترويسات الطلب، أو أي بيانات خاصة بالطلب تحتاج إليها إجراءاتك.

يُنشأ السياق قبل أي إجراء، مما يجعله المكان المناسب لإعداد المصادقة واتصال قاعدة البيانات.

في createTRPCContext، استدعِ getServerSession(authOptions) من next-auth/next. أرفق النتيجة بكائن السياق: return { session: await getServerSession(authOptions), db }. أصبحت جميع الإجراءات تملك الآن إمكانية الوصول إلى ctx.session.

إذا كانت session تساوي null، فهذا يعني أن المستخدم غير مُصادق عليه. ويمكن للإجراءات التحقق من ذلك لإعادة البيانات بشكل مشروط أو طرح خطأ.

عرّف middleware يتحقق من ctx.session: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

يمرّر استدعاء next() السياق المضيّق، الذي يحتوي على session غير فارغة، إلى middlewares اللاحقة ومعالج الإجراء.

ألّف middleware مع publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). والآن يمتلك أي معالج يُعرّف باستخدام protectedProcedure.query() أو protectedProcedure.mutation() جلسة غير فارغة في ctx تلقائيًا.

يستنتج TypeScript أن ctx.session غير فارغة داخل الإجراءات المحمية، لأن middleware كان سيطرح خطأ قبل الوصول إلى المعالج.

استبدل publicProcedure بـ protectedProcedure لنقاط النهاية التي تتطلب المصادقة: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). يعرف TypeScript أن ctx.session غير فارغة هنا، لذا فإن الوصول إلى ctx.session.user.id آمن دون فحص null.

تتلقى الطلبات غير المصادق عليها تلقائيًا استجابة 401 UNAUTHORIZED قبل تنفيذ المعالج.

مرّر دالة headers إلى httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. تُنفّذ الدالة قبل كل دفعة من الطلبات.

يُستخدم هذا عند مصادقة tRPC من عميل React Native أو أي عميل لا يعتمد على Next.js ويدير رموز المصادقة الخاصة به.

بالنسبة إلى SSR في موجّه Pages ضمن Next.js، أنشئ مساعدًا من جانب الخادم: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). استخدم helpers.post.getAll.prefetch() داخل getServerSideProps.

حوّل الحالة التي جرى جلبها مسبقًا باستخدام dehydrate(queryClient) ومرّرها ضمن props. وعلى العميل، يستعيد QueryClient حالته من هذه البيانات، مما يتجنب إعادة الجلب عند التحميل الأول.

غلّف ملف _app.tsx في Next.js بالمكوّن Hydrate المستورد من @tanstack/react-query. مرّر pageProps.trpcState إلى الخاصية state. يؤدي ذلك إلى استعادة ذاكرة التخزين المؤقت للاستعلامات التي جرى جلبها مسبقًا على العميل من حالة الخادم المتسلسلة.

باستخدام هذا الإعداد، يرى المستخدمون صفحات مكتملة البيانات فورًا دون مؤشرات تحميل من جانب العميل عند التنقل الأولي.

اطرح TRPCError باستخدام رموز مناسبة دلاليًا لـ HTTP: UNAUTHORIZED (401)، وFORBIDDEN (403)، وNOT_FOUND (404)، وBAD_REQUEST (400)، وINTERNAL_SERVER_ERROR (500). يربط عميل tRPC هذه الرموز بحالات الخطأ المناسبة في نتيجة hook.

يمكن أن يحتوي الحقل message على تفاصيل موجهة للمستخدم، لكن تجنب كشف معلومات الخادم الحساسة في رسائل الخطأ في بيئة الإنتاج.

يعمل tRPC مع عملاء React Native باستخدام نوع AppRouter نفسه. استبدل httpBatchLink بـ httpLink، إذ يعمل RN fetch بالطريقة نفسها، واضبط ترويسات المصادقة. ويعمل محوّل @trpc/react-query بالطريقة نفسها التي يعمل بها في إعداد الويب.

وهذا يعني أن monorepo يمكنه مشاركة موجّه tRPC واحد بين تطبيق ويب يستخدم Next.js وتطبيق Expo React Native، مع أمان كامل للأنواع في كليهما.

وسّع نمط middleware للتحكم في الوصول المستند إلى الأدوار: تحقّق من ctx.session.user.role واطرح TRPCError({ code: 'FORBIDDEN' }) إذا كان الدور غير كافٍ. أنشئ adminProcedure = publicProcedure.use(isAdmin) لنقاط النهاية الخاصة بالمسؤولين فقط.

كدّس عدة middlewares للتعامل مع التفويض المعقد: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

كيف يُنشأ إجراء محمي في tRPC لفرض المصادقة؟

يُنشأ سياق tRPC لكل طلب، ويحتفظ بالجلسة وعميل قاعدة البيانات والبيانات الأخرى الخاصة بنطاق الطلب. تُنشأ الإجراءات المحمية بتركيب middleware يتحقق من الجلسة مع publicProcedure باستخدام .use(). ويستخدم التصيير من جانب الخادم createServerSideHelpers للجلب المسبق، ثم Hydrate لاستعادة ذاكرة التخزين المؤقت على العميل.

تُمرّر ترويسات المصادقة للعملاء الذين لا يستخدمون Next.js عبر خيار headers في httpBatchLink.