TypeScript Academy · Урок

Архитектура tRPC

Узнайте, как tRPC устраняет дублирование схем API

«Архитектура tRPC» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения TypeScript Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс TypeScript Academy содержит 4 уроков всего.

Проблема сквозной типизации

В обычном веб-приложении сервер определяет API, а клиент его вызывает. Поддерживать их типы синхронизированными сложно: изменив поле на сервере, Вы можете незаметно сломать клиент во время выполнения. tRPC решает эту проблему, напрямую разделяя типы и не требуя генерации кода.

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

Что такое tRPC

tRPC — это библиотека для создания полностью типизированных API на TypeScript. Сервер определяет процедуры, а клиент вызывает их так, будто это локальные функции, получая полное автодополнение и проверку типов, выведенные из кода сервера.

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

Без генерации кода

В отличие от рабочих процессов GraphQL или OpenAPI, tRPC не требует этапа генерации кода. Не нужны файл схемы для компиляции или сгенерированный клиент. Типы передаются от сервера к клиенту исключительно через вывод TypeScript во время компиляции.

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

Маршрутизатор — это контракт

Центральным элементом tRPC является маршрутизатор. Это дерево процедур (запросов и мутаций). Объект маршрутизатора на сервере, а точнее его выведенный тип, — единственный источник истины, общий для сервера и клиента.

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

Как совместно используются типы

Сервер экспортирует только тип своего router, а не его реализацию. client импортирует этот тип и использует его для типизации прокси-клиента. Код сервера не попадает в браузер: передаются только типы, которые удаляются во время сборки.

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

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

Запросы и мутации

Процедуры бывают двух основных видов. query считывает данные и обычно является идемпотентным. mutation изменяет данные. Это различие соответствует семантике кэширования и HTTP и определяет способ вызова процедур из client.

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

Выполнение и типы

У tRPC есть два уровня. Во время выполнения вызовы представляют собой JSON поверх HTTP и обрабатываются адаптером. Во время компиляции общий тип AppRouter обеспечивает полную проверку каждого вызова. Уровень выполнения минимален, а ценность заключается в безопасности типов.

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

Почему вывод типов лучше генерации кода

Поскольку типы выводятся автоматически, невозможно забыть о шаге синхронизации. Измените процедуру — и client сразу отразит это изменение, показав красные волнистые подчёркивания там, где вызовы больше не соответствуют определению. Обратная связь мгновенно появляется прямо в редакторе.

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

Где применяется tRPC

tRPC особенно хорошо подходит для полностековых монорепозиториев на TypeScript, где client и сервер используют одну кодовую базу, например для приложений Next.js. tRPC не предназначен для общедоступных программных интерфейсов, которые используют другие языки; для них по-прежнему нужна независимая от языка схема, например OpenAPI или GraphQL.

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

Общая картина

Процесс выглядит так: определить процедуры в router, экспортировать тип router, подключить HTTP-адаптер и создать типизированный client на основе этого типа. Каждый вызов проверяется в соответствии с контрактом сервера, при этом сгенерированный код не нужен. В следующих уроках мы создадим каждую из этих частей.

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

Доверьтесь компилятору

Главное изменение мышления заключается в следующем: контракт программного интерфейса находится в типах, проверяемых компилятором, а не только в документации или проверках во время выполнения. Если код компилируется, client и сервер согласованы. Именно это означает «сквозная безопасность типов».

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

Проверьте себя

Проверьте, насколько хорошо Вы поняли архитектуру tRPC.

Повторение

Вы изучили модель tRPC.

router — это контракт, а его тип — единственный источник истины.
Сервер экспортирует только тип AppRouter, но не код.
query считывает данные, mutation записывает их; во время выполнения используется JSON поверх HTTP.
Безопасность типов обеспечивается выводом типов, без этапа генерации кода.

Далее: определение router и процедур.

Часто задаваемые вопросы

Урок «Архитектура tRPC» бесплатный?

Да — полный текст урока «Архитектура tRPC» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 4 уроков всего.

Чему я научусь в уроке «Архитектура tRPC»?

Узнайте, как tRPC устраняет дублирование схем API Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать TypeScript Academy?

Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Архитектура tRPC»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке TypeScript Academy?

Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к TypeScript Academy