0Pricing
TypeScript Academy · Lekcja

Definiowanie routerów i procedur

Buduj zapytania i mutacje z walidacją danych wejściowych

Definiowanie routerów i procedur to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Inicjalizowanie tRPC

Każdy backend tRPC zaczyna się od utworzenia instancji za pomocą initTRPC. Zwraca ona buildery routerów i procedur. Zwykle tworzy się ją raz, a następnie eksportuje potrzebne elementy.

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

Pierwsza procedura

Procedura to pojedynczy endpoint API. Najprostsza procedura jest zapytaniem, które zwraca wartość. publicProcedure.query definiuje endpoint do odczytu, który nie przyjmuje danych wejściowych.

import { router, publicProcedure } from './trpc';

const appRouter = router({
  health: publicProcedure.query(() => 'ok'),
});

Walidowanie danych wejściowych

Procedury deklarują dane wejściowe za pomocą walidatora, najczęściej schematu zod. .input(schema) zarówno przeprowadza walidację w czasie wykonywania, jak i wyprowadza typ danych wejściowych dla resolvera i klienta.

import { z } from 'zod';

const greet = publicProcedure
  .input(z.object({ name: z.string() }))
  .query(({ input }) => 'Hello, ' + input.name);

Odczytywanie danych wejściowych

Wewnątrz resolvera zwalidowane dane wejściowe są dostępne jako input i są w pełni typowane na podstawie schematu. Nie trzeba wykonywać ręcznego rzutowania — zod i tRPC wspólnie wyprowadzają strukturę danych.

const byId = publicProcedure
  .input(z.object({ id: z.number() }))
  .query(({ input }) => {
    // input.id is number
    return { id: input.id, name: 'Alice' };
  });

Mutacje

Elementu .mutation należy używać do operacji zmieniających dane. Struktura jest taka sama jak w przypadku zapytania, ale sygnalizuje zapis, co wpływa na buforowanie po stronie klienta i metodę HTTP.

const createUser = publicProcedure
  .input(z.object({ name: z.string() }))
  .mutation(({ input }) => {
    return { id: 1, name: input.name };
  });

Budowanie appRouter

Procedury grupuje się w routerze, przekazując obiekt do router(...). Każdy klucz staje się nazwą wywoływanej procedury. Ten appRouter stanowi całe API.

const appRouter = router({
  greet,
  byId,
  createUser,
});

Zagnieżdżone routery

Routery można zagnieżdżać, aby uporządkować duże interfejsy API. Wartością w obiekcie routera może być kolejny router, co pozwala tworzyć wywołania z przestrzeniami nazw, takie jak user.byId.

const userRouter = router({ byId, createUser });

const appRouter = router({
  user: userRouter,
  greet,
});
// call paths: user.byId, user.createUser, greet

Eksportowanie typu routera

Najważniejszym eksportem jest typ routera. Klient zaimportuje go, aby uzyskać pełne bezpieczeństwo typów. Należy eksportować wartość na potrzeby adaptera serwera oraz typ na potrzeby klienta.

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

Dołączanie adaptera

Aby udostępnić router przez HTTP, należy dołączyć adapter. tRPC udostępnia adaptery dla samodzielnego środowiska Node, Express, Next.js, Fetch i innych. Adapter przekształca przychodzące żądania w wywołania procedur.

import { createHTTPServer } from '@trpc/server/adapters/standalone';

createHTTPServer({ router: appRouter }).listen(3000);

Organizowanie plików

Typowy układ obejmuje plik trpc.ts z initTRPC oraz eksportowanymi builderami router/publicProcedure, routery funkcjonalności w osobnych plikach i główny appRouter, który je składa. Umieszczenie initTRPC w jednym miejscu zapobiega tworzeniu wielu instancji.

// trpc.ts: initTRPC.create(), export router + publicProcedure
// routers/user.ts: userRouter
// router.ts: appRouter = router({ user: userRouter })

Podsumowanie inferencji danych wejściowych

Ponieważ .input(schema) zarówno waliduje dane, jak i wyprowadza ich typ, schemat definiuje się raz, uzyskując jednocześnie ochronę w czasie wykonywania i typ statyczny. Klient zobaczy dokładnie te dane wejściowe, których oczekuje każda procedura, wyprowadzone na podstawie tych schematów.

const search = publicProcedure
  .input(z.object({ q: z.string(), page: z.number().optional() }))
  .query(({ input }) => ({ q: input.q, page: input.page ?? 1 }));

Szybkie sprawdzenie

Proszę sprawdzić swoje rozumienie routerów i procedur.

Podsumowanie

Zbudowali Państwo backend tRPC.

  • initTRPC.create() udostępnia buildery router i procedure.
  • .input(schema) waliduje i wyprowadza typ danych wejściowych.
  • .query odczytuje dane, a .mutation je zapisuje.
  • Procedury można składać w appRouter i eksportować type AppRouter = typeof appRouter.

Następnie: używanie API za pomocą w pełni typowanego klienta.

Często zadawane pytania

Czy lekcja „Definiowanie routerów i procedur” jest bezpłatna?

Tak — pełny tekst „Definiowanie routerów i procedur” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Definiowanie routerów i procedur”?

Buduj zapytania i mutacje z walidacją danych wejściowych Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?

Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Definiowanie routerów i procedur”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?

Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Architektura tRPC
  2. Definiowanie routerów i procedur
  3. Wnioskowanie typów po stronie klienta i serwera
  4. Middleware i kontekst
← Powrót do TypeScript Academy