مقدمه tRPC: TypeScript یکپارچه و تمام پشته

پروژه tRPC تایپ قوی با قابلیت‌های جاوا اسکریپت سمت سرور را در یک پروتکل تعامل مشتری و سرور جمع می‌کند. بیایید ببینیم چگونه کار می کند.

• تماس رویه از راه دور TypeScript
• ارتباط مشتری و سرور با tRPC
• tRPC در قسمت جلو
• tRPC برای TypeScript تمام پشته

جاوا اسکریپت در زمان خود شاهد جهش های نفس گیر تکاملی بوده است. از جمله معرفی جاوا اسکریپت سمت سرور با Node.js و تایپ قوی با TypeScript بود. پروژه tRPC این دو نوآوری را با هم ترکیب می کند تا به توسعه دهندگان اجازه دهد تا مشتری و سرور را در یک نحو واحد تعریف و در هم آمیزند. توسعه دهندگان مزایای استنتاج نوع را برای کل پشته بدون واسطه دریافت می کنند. بیایید نگاهی به tRPC و جایی که در جعبه ابزار TypeScript تمام پشته شما قرار می گیرد بیاندازیم.

تماس رویه از راه دور TypeScript

tRPC مخفف عبارت Typescript Remote Procedure Call است. به جای اینکه یک تعریف API برای بک اند شما با چیزی مانند OpenAPI یا GraphQL تولید کند، tRPC مستقیماً نقاط پایانی TypeScript شما را استنتاج و اعمال می کند. همچنین پارامترهای سمت کلاینت را روی سرور اعمال می کند. اگر از قبل کل پشته خود را به زبانی قوی مانند TypeScript می نویسید، این ترتیب منطقی است. چرا مولفه دیگری را برای هماهنگ کردن چیزی که می توانید به سادگی برون یابی کنید، معرفی کنید؟

خالق tRPC الکس جوهانسون توضیح می‌دهد:

tRPC به شما یک نحو برای تعریف نقاط انتهایی پایان می دهد، اما خودش یک سرور نیست. در عوض، می‌توانید tRPC API را در محیط‌های مختلفی از Node گرفته تا محیط‌های بدون سرور مانند کارگران CloudFlare میزبانی کنید. حتی می توانید یک بک اند tRPC را به میان افزار Express تبدیل کنید.

در سمت کلاینت، tRPC دارای پیوندهایی برای طیف وسیعی از فریم ورک‌های رایج مانند React و SvelteKit.

همه اینها به این معنی است که tRPC می تواند تجربه توسعه دهنده را در طیف وسیعی از پشته ها با حداقل تلاش و تغییرات بهبود بخشد. توسعه دهندگان اطلاعات نوع و اعمال را در سراسر مرزهای API با هزینه کمی به دست می آورند.

ارتباط کلاینت-سرور با tRPC

tRPC پروتکلی برای تعامل بین کلاینت و سرور است. تمام ارتباطات مشتری-سرور توسط پروتکل مدیریت می شود و بنابراین API سمت سرور مختص tRPC است. اگرچه tRPC برای ساختن یک برنامه فول استک که نیاز به تعامل بین قسمت جلویی و پشتی دارد، شاید ایده آل ترین گزینه باشد، می توان با استفاده از پروژه ای مانند trpc-openapi.

تنظیم اکسپرس

به ساخت سرتاسر typeafe مراجعه کنید API با tRPC برای راهنمای گام به گام برای راه‌اندازی یک محیط محلی با Express.js و React.

شما می توانید tRPC را در انواع پشته ها اعمال کنید. هر زمان که هم کلاینت و هم سرور را بتوان در TypeScript تعریف کرد، tRPC می تواند اجرای نوع را فراهم کند و در زمان توسعه و کامپایل کمک کند. برای آشنایی با tRPC، از نمونه برنامه کاربردی TodoMVC در CodeSandBox. برنامه TodoMVC یک برنامه کاری متعارف با tRPC و Next.js است. صفحه فرود برنامه چیزی شبیه به شکل ۱ است. (توجه داشته باشید که برای ویرایش جعبه ایمنی، باید وارد شوید و آن را فورک کنید.)

شکل ۱. برنامه tRPC TodoMVC در CodeSandBox

Next.js در حال حاضر یک چارچوب تمام پشته است. tRPC پشتیبانی بیشتری برای سیم‌کشی برنامه ارائه می‌کند، اما فرآیند اصلی برای کاربران Next.js آشنا خواهد بود:

1. روتر(های) API که درخواست های back-end را مدیریت می کنند را تعریف کنید.
2. تعریف نوع روتر را صادر کنید.
3. از تعریف نوع در قسمت جلویی استفاده کنید.

تعریف روتر tRPC را در /src/server/routers/_app.ts خواهید یافت (در کاوشگر فایل در سمت چپ یافت می‌شود). این فایل فقط فایل todo.ts را وارد می کند و آن را در یک شی روتر از کتابخانه trpc می پیچد، همانطور که در فهرست ۱ نشان داده شده است. 

import { router } from '../trpc';
import { todoRouter } from './todo';

export const appRouter = router({
  todo: todoRouter,
});

export type AppRouter = typeof appRouter;

در فهرست ۱ توجه به دو عنصر مهم است. اول، نشان می دهد که چگونه روترها می توانند روترهای دیگر را وارد کرده و از آنها استفاده کنند. این به ما امکان می دهد API های پیچیده را از روترهای مختلف در فایل های مختلف بسازیم. دوم، توجه کنید که این فایل نوع AppRouter = typeof appRouter را صادر می کند. به این دلیل که در قسمت جلویی، از تعریف نوع برای کمک به استفاده از API خود استفاده می‌کنیم (و tRPC کمک می‌کند مطمئن شویم که هیچ تغییری در ساخت‌وساز نمی‌لغزد).

اگر فایل todo.ts وارد شده را باز کنید، متوجه نحوه تعریف مسیرها در tRPC خواهید شد. هر نقطه پایانی دارای سه مرحله ممکن اساسی است:

1. ورودی: ورودی خام را دریافت کنید، آن را تأیید کنید و آن را به پارامترهایی با تایپ قوی تبدیل کنید.
2. پرس و جو: به درخواست‌های سبک GET رسیدگی کنید.
3. جهش: رسیدگی به درخواست‌های سبک PUT/POST.

در اینجا توجه کنید که تمایز قوی بین پرس و جو و جهش مشابه GraphQL است.

می‌توانید با کاوش در todo.ts و مشاهده قطعه کد در فهرست ۲، احساسی نسبت به نحوه کار روتر پیدا کنید.

import { z } from 'zod';
import { baseProcedure, router } from '../trpc';
// ...
add: baseProcedure
    .input(
      z.object({
        id: z.string().optional(),
        text: z.string().min(1),
      }),
    )
    .mutation(async ({ ctx, input }) => {
      const todo = await ctx.task.create({
        data: input,
      });
      return todo;
    }),

در فهرست ۲، add route برای مدیریت افزودن TODOهای جدید تعریف شده است. از یک شی baseProcedure برای انتزاع نمونه سازی از زمینه tRPC استفاده می کند. (برای مشاهده نحوه انجام این کار، فایل /src/server/trpc.ts را بررسی کنید. توجه داشته باشید که از پروژه superjson برای کمک به مقابله با JSON غنی.) عملکرد baseProcedure.input اعتبارسنجی و تایپ را انجام می دهد. از کتابخانه zod برای کمک به اعمال اعتبار و تبدیل استفاده می‌کند. هر آنچه که توسط روش input برگردانده می شود، سپس به عنوان آرگومان به روش mutation داده می شود.

روش mutation یک تابع همگام با دو پارامتر را می پذیرد: یک متن و یک ورودی. اگر ماوس را روی آن قرار دهید یا اطلاعات متنی IDE را درگیر کنید، خواهید دید که شی ورودی نوع شی ارسال شده از ورودی را با فیلدهای id و text نشان می‌دهد. p>

شکل ۲. بررسی نوع ورودی دریافت شده توسط روش جهش

در روش جهش، از شی ctx برای دسترسی به زمینه برنامه استفاده می کنیم، جایی که یک Prisma برای تداوم TODO جدید استفاده می شود.

tRPC پشتیبانی قوی از Next.js دارد. پیوند دادن Next.js به پیکربندی tRPC در /src/pages/api/trpc/[trpc].ts انجام می‌شود. بسیار ساده است که آنچه را که در روترها دیدیم به قسمت پشتی Next.js نگاشت کنیم.

tRPC در قسمت جلو

اکنون اجازه دهید به قسمت جلویی بپریم. قسمت جلویی Next.js با tRPC در /src/pages/_app.ts متحد شده است. مانند قسمت پشتی، یکپارچه سازی نسبتاً ساده است.

کار واقعی خروجی قسمت جلویی در /src/pages/[filter].tsx اتفاق می‌افتد. این فایل بیشتر یک رابط کاربری معمولی React یا Next.js است، اما دارای قدرت های فوق العاده از tRPC است. به طور عمده، نوع AppRouter را از تعریف سمت سرور ما می کشد و تغییرات را از آنجا اعمال می کند.

برای دریافت سریع حسی از نوع استنتاج در محل کار، فایل todo.ts را مجدداً مشاهده کنید و یک تغییر اساسی ایجاد کنید. به عنوان مثال، من نام فیلد متنی را در روش add.mutation به text2 تغییر دادم. انجام این کار باعث ایجاد خطا در IDE می شود.

به عنوان مثال، خطای «ویژگی 'text' در نوع '{ id?: string | تعریف نشده؛ text2: رشته; }'.typescript(2339)” در [filter].tsx مشابه شکل ۳ مشاهده می شود. . به طور کلی، tRPC انواع را در سراسر پشته اعمال می کند.

شکل ۳. خطاهای سمت کلاینت که منعکس کننده تغییرات پشتیبان هستند

یکی دیگر از مزایای tRPC در قسمت جلویی این است که بسیاری از تعاملات API توسط tRPC مدیریت می شود، به جای اینکه نیاز به سیم کشی آن با چیزی مانند fetch() API باشد. به عنوان مثال، برای استفاده از add mutation API، [filter].tsx از tRPC همانطور که در فهرست ۳ مشاهده می شود استفاده می کند.

const addTask = trpc.todo.add.useMutation({
    async onMutate({ text }) {
      await utils.todo.all.cancel();
      const tasks = allTasks.data ?? [];
      utils.todo.all.setData(undefined, [
        ...tasks,
        {
          id: `${Math.random()}`,
          completed: false,
          text,
          createdAt: new Date(),
        },
      ]);
    },
  });

عملکرد addTask کار تعامل از قسمت جلویی تا API راه دور را انجام می دهد. این در trpc.todo.add.useMutation پیچیده شده است که توسط tRPC بر اساس نقطه پایانی سرور تولید می شود. این نحو به ما امکان می‌دهد با انتهای پشتی به روشی شفاف، بدون لوله‌کشی زیاد تعامل داشته باشیم و تایپ را حفظ کنیم.

tRPC for full-stack TypeScript

برای پروژه‌هایی که قبلاً از TypeScript استفاده می‌کنند، منطقی است که به TypeScript اجازه دهیم رابط مشتری-سرور را هدایت کند. tRPC نیازی به فینگلینگ یا تغییرات زیادی در نحوه استفاده از فناوری های موجود ندارد، که خوب است. داشتن اطلاعات اضافی در طول توسعه بسیار مفید است. به طور کلی، tRPC تجربه توسعه دهنده را بدون هزینه زیاد بهبود می بخشد. این یک افزونه خوش آمد به جعبه ابزار TypeScript تمام پشته است.