0Pricing
TypeScript Academy · Lekcja

Architektura tRPC

Dowiedz się, jak tRPC eliminuje duplikowanie schematów API

Architektura tRPC to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 1 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.

Problem pełnego przepływu

W typowej aplikacji internetowej serwer definiuje API, a klient z niego korzysta. Utrzymanie zgodności ich typów jest trudne: po zmianie pola na serwerze klient może przestać działać dopiero w czasie wykonywania. tRPC rozwiązuje ten problem, udostępniając typy bezpośrednio, bez generowania kodu.

// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they drift

Czym jest tRPC

tRPC to biblioteka do tworzenia w pełni typowanych interfejsów API w TypeScript. Serwer definiuje procedury, a klient wywołuje je tak, jakby były lokalnymi funkcjami, uzyskując pełne autouzupełnianie i sprawdzanie typów wywnioskowane z kodu serwera.

// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the server

Brak generowania kodu

W przeciwieństwie do procesów opartych na GraphQL lub OpenAPI tRPC nie wymaga etapu generowania kodu. Nie ma pliku schematu do skompilowania ani wygenerowanego klienta. Typy przepływają z serwera do klienta wyłącznie dzięki wnioskowaniu TypeScript podczas kompilacji.

// No .graphql files, no generated SDK
// Just import a type from the server package

Router jest kontraktem

Centralnym elementem tRPC jest router. To drzewo procedur (zapytań i mutacji). Obiekt routera na serwerze, a dokładniej wywnioskowany dla niego typ, jest jednym źródłem prawdy współdzielonym z klientem.

// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contract

Udostępnianie typów

Serwer eksportuje wyłącznie typ swojego routera, a nie jego implementację. Klient importuje ten typ i używa go do typowania klienta proxy. Żaden kod serwera nie trafia do przeglądarki — tylko typy, które są usuwane podczas kompilacji.

// server.ts
export type AppRouter = typeof appRouter;

// client.ts
import type { AppRouter } from '../server';

Zapytania i mutacje

Procedury występują w dwóch głównych rodzajach. Zapytanie odczytuje dane i zazwyczaj jest idempotentne. Mutacja zmienia dane. To rozróżnienie odpowiada za sposób buforowania i semantykę HTTP oraz wpływa na sposób ich wywoływania przez klienta.

// client.user.list.query()      -> read
// client.user.create.mutate(...) -> write

Runtime a typy

tRPC ma dwie warstwy. W czasie wykonywania wywołania są obsługiwane przez adapter i przesyłane jako JSON przez HTTP. W czasie kompilacji współdzielony typ AppRouter zapewnia pełne sprawdzanie każdego wywołania. Warstwa runtime jest niewielka — wartość stanowi bezpieczeństwo typów.

// Runtime: POST /trpc/user.byId  body: {"input":1}
// Types: client.user.byId.query(1) is checked end to end

Dlaczego inferencja jest lepsza niż generowanie kodu

Ponieważ typy są wyprowadzane automatycznie, nie ma kroku synchronizacji, o którym można zapomnieć. Po edycji procedury klient natychmiast odzwierciedla zmianę, wyświetlając czerwone podkreślenia faliste tam, gdzie wywołania przestają pasować. Informacja zwrotna jest natychmiastowa i dostępna bezpośrednio w edytorze.

// Add a required input field on the server
// -> every client call missing it becomes a type error

Gdzie znajduje zastosowanie tRPC

tRPC sprawdza się w monorepozytoriach full-stack TypeScript, w których klient i serwer współdzielą bazę kodu, na przykład w aplikacjach Next.js. Nie służy do tworzenia publicznych interfejsów API używanych przez inne języki; w takich przypadkach nadal potrzebny jest niezależny od języka schemat, taki jak OpenAPI lub GraphQL.

// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumers

Szerszy obraz

Przepływ wygląda następująco: definiuje się procedury w routerze, eksportuje typ routera, dołącza adapter HTTP i tworzy typowanego klienta na podstawie tego typu. Każde wywołanie jest sprawdzane względem kontraktu serwera, bez generowania kodu. W następnych lekcjach zbudują Państwo każdy z tych elementów.

// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for auth

Zaufanie do kompilatora

Zmiana sposobu myślenia polega na tym, że kontrakt API znajduje się w typach egzekwowanych przez kompilator, a nie wyłącznie w dokumentacji lub walidacji w czasie wykonywania. Jeśli kod się kompiluje, klient i serwer są zgodne. To właśnie oznacza „bezpieczeństwo typów end-to-end”.

// If client.ts compiles, it matches the current server.

Szybkie sprawdzenie

Proszę sprawdzić swoje rozumienie architektury tRPC.

Podsumowanie

Poznali Państwo model tRPC.

  • Router jest kontraktem, a jego typ stanowi jedyne źródło prawdy.
  • Serwer eksportuje tylko typ AppRouter, a nie kod.
  • Zapytania odczytują dane, mutacje je zapisują, a warstwa runtime używa JSON przez HTTP.
  • Bezpieczeństwo typów wynika z inferencji, bez etapu generowania kodu.

Następnie: definiowanie routerów i procedur.

Często zadawane pytania

Czy lekcja „Architektura tRPC” jest bezpłatna?

Tak — pełny tekst „Architektura tRPC” 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 „Architektura tRPC”?

Dowiedz się, jak tRPC eliminuje duplikowanie schematów API Ć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 1 z 4.

Ile czasu zajmuje lekcja „Architektura tRPC”?

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