Процедура вместо маршрута: @Router, @Query, @Mutation

В миниатюре процедура собиралась одним вызовом: procedure(схема, обработчик). В настоящем tRPC то же самое пишется цепочкой: t.procedure.input(схема).query(обработчик). Длиннее, и поначалу кажется, что это вкусовщина. Не вкусовщина: цепочка решает задачу, которой у миниатюры не было.

Задача такая. У половины процедур настройки общие: одни открыты гостю, другие требуют токена, третьи ещё и считают частоту вызовов. С тремя аргументами это пишется в каждой процедуре заново. С цепочкой — один раз: const protectedProcedure = t.procedure.use(проверкаТокена), и дальше от этой заготовки отходят десятки процедур. Чтобы так было можно, шаг обязан не править заготовку, а возвращать новую — иначе первая же процедура испортила бы её всем остальным.

Соберём такой строитель сами, поверх схем и call из типизированного клиента главы 6.

// Схемы, procedure и call — в подложке, здесь их типы
type Issue = { path: string; message: string };
type Result<T> = { ok: true; value: T } | { ok: false; issues: Issue[] };
interface Schema<T> {
  check(value: unknown, path: string): Result<T>;
}
type Infer<S> = S extends Schema<infer T> ? T : never;
type Procedure<I, O> = { input: Schema<I>; run: (input: I) => O };
declare const text: Schema<string>;
declare const int: Schema<number>;
declare function oneOf<T extends string>(...allowed: T[]): Schema<T>;
declare function object<F extends Record<string, Schema<unknown>>>(fields: F): Schema<{ [K in keyof F]: Infer<F[K]> }>;
declare function call(router: unknown, path: string, raw: unknown): unknown;

type Note = { id: number; title: string; status: "draft" | "published" };
const notes: Note[] = [{ id: 1, title: "Первая заметка", status: "published" }];

// Шаг возвращает нового строителя: заготовку с общими настройками потом переиспользуют
type Builder<I> = {
  input<T>(schema: Schema<T>): Builder<T>;
  query<O>(run: (opts: { input: I }) => O): Procedure<I, O>;
};

function builder<I>(input: Schema<I>): Builder<I> {
  return {
    input: (schema) => builder(schema),
    // обработчику приезжает не сам вход, а объект с полем input: туда потом добавится контекст
    query: (run) => ({ input, run: (value) => run({ input: value }) }),
  };
}

// Начало цепочки: схемы ещё нет, вход не разбирается
const anything: Schema<unknown> = { check: (value) => ({ ok: true, value }) };
const base = builder(anything);

const router = {
  notes: {
    byId: base.input(object({ id: int })).query(({ input }) => notes.find((note) => note.id === input.id) ?? null),
    create: base.input(object({ title: text, status: oneOf("draft", "published") })).query(({ input }) => {
      const note: Note = { id: notes.length + 1, ...input };
      notes.push(note);
      return note;
    }),
  },
  // Цепочку можно оборвать сразу: схемы нет, разбирать нечего
  ping: base.query(() => "жив"),
};

console.log(call(router, "notes.byId", { id: 1 }));
console.log(call(router, "notes.create", { title: "  Вторая  ", status: "draft" }));
console.log(call(router, "ping", null));

// Та же заготовка, ещё одна схема входа
const count = base.input(object({})).query(() => notes.length);
console.log("всего заметок:", count.run({}));

// @ts-expect-error у схемы входа одно поле, и тип обработчика пришёл из неё
const broken = base.input(object({ id: int })).query(({ input }) => input.title);

base — начало цепочки: схемы ещё нет, и вход у неё unknown. Каждый input отдаёт нового строителя, у которого параметр типа уже другой, а query цепочку закрывает: из строителя получается обычная процедура — та самая пара «схема и обработчик», которую умеет звать call. Заготовка при этом цела: count отошёл от того же base после двух процедур и получил свою схему, а не чужую.

Обработчику приезжает не сам вход, а объект { input }, и в миниатюре это лишняя пара скобок. В настоящем tRPC рядом с input лежат ctx, path, signal и номер вызова в пачке (@trpc/server 11.18.0, ProcedureResolverOptions). Добавить в объект новое поле можно, не тронув ни одной процедуры; добавить второй аргумент — только сломав все.

Последняя строка примера помечена @ts-expect-error, и пометка тут не для красоты: тип обработчика пришёл из схемы входа, а у объекта { id: число } поля title нет. Снимите пометку — компилятор скажет это вслух, хотя ни одного типа в обработчике не написано.

Цепочка — не мода на «текучие интерфейсы». Это единственный способ дать процедуре общую заготовку и не потерять тип входа: каждый шаг возвращает новый тип, а не правит старый.

Цепочка кончается не просто обработчиком, а видом: .query(), .mutation() или .subscription(). Маршрутизации вид не нужен — имя процедуры и так едет строкой, и роутер находит её по имени. Вид нужен другому: транспорту.

GET и POST различаются не буквами. GET браузер повторит сам, положит в кеш, покажет в адресной строке и даст на него ссылку; прокси запишет адрес в журнал целиком, вместе со входом. POST не повторяется, не кешируется, ссылкой не становится. Объявив процедуру запросом, вы всё это разрешаете; объявив мутацией — запрещаете. Поэтому вид и стоит в объявлении, а не выводится из того, что обработчик делает.

// Схемы и parse — в подложке, здесь их типы
type Issue = { path: string; message: string };
type Result<T> = { ok: true; value: T } | { ok: false; issues: Issue[] };
interface Schema<T> {
  check(value: unknown, path: string): Result<T>;
}
type Infer<S> = S extends Schema<infer T> ? T : never;
declare const text: Schema<string>;
declare const int: Schema<number>;
declare function object<F extends Record<string, Schema<unknown>>>(fields: F): Schema<{ [K in keyof F]: Infer<F[K]> }>;
declare function parse<T>(schema: Schema<T>, value: unknown, path: string): T;

type Note = { id: number; title: string };
const notes: Note[] = [{ id: 1, title: "Первая заметка" }];

// У процедуры появляется третье поле: чем она объявлена — чтением или правкой
type Kind = "query" | "mutation";
type Procedure<I, O> = { kind: Kind; input: Schema<I>; run: (input: I) => O };

function procedure<I, O>(kind: Kind, input: Schema<I>, run: (input: I) => O): Procedure<I, O> {
  return { kind, input, run };
}

const router = {
  notes: {
    byId: procedure("query", object({ id: int }), (input) => notes.find((note) => note.id === input.id) ?? null),
    create: procedure("mutation", object({ title: text }), (input) => {
      const note = { id: notes.length + 1, title: input.title };
      notes.push(note);
      return note;
    }),
  },
};

// По проводу приезжают две строки: метод и путь
function route(method: "GET" | "POST", path: string, raw: unknown): unknown {
  let node: unknown = router;
  for (const step of path.split(".")) {
    node = typeof node === "object" && node !== null ? (node as Record<string, unknown>)[step] : undefined;
  }
  const found = node as Procedure<unknown, unknown> | undefined;
  if (!found || typeof found.run !== "function") throw new TypeError(`нет процедуры ${path}`);
  const allowed = found.kind === "query" ? "GET" : "POST";
  if (method !== allowed) throw new TypeError(`${method} к процедуре вида ${found.kind}: этот вид ездит методом ${allowed}`);
  return found.run(parse(found.input, raw, "input"));
}

const wire: [string, string, unknown][] = [
  ["GET", "notes.byId", { id: 1 }],
  ["POST", "notes.create", { title: "Вторая" }],
  ["GET", "notes.create", { title: "Третья" }],
  ["POST", "notes.byId", { id: 1 }],
  ["GET", "notes.remove", { id: 1 }],
];

for (const [method, path, raw] of wire) {
  try {
    console.log(method, path, "→", route(method as "GET" | "POST", path, raw));
  } catch (error) {
    console.log(method, path, "→", error instanceof Error ? error.message : error);
  }
}

Обе половины сошлись: GET к мутации и POST к запросу отвергнуты до разбора входа, а несуществующее имя не доходит даже до проверки метода — по такому пути в роутере просто нет ветки. Ровно так отвечает и настоящий tRPC, только другими словами; его ответ будет ниже, в разделе про Nest.

Где едет вход, тоже решает вид. У запроса он уезжает в строке запроса — ?input={"id":1}, — у мутации в теле. Это не соглашение tRPC, а следствие метода: у GET тела нет.

Вид — первое, что в процедуре стоит объявить, и последнее, что стоит менять. Смена query на mutation меняет метод, а значит, и всё поведение кешей и ссылок вокруг.

Пакет @trpc/server можно потрогать, не поднимая ни порта, ни Nest. Точка сборки — initTRPC.create(): она отдаёт t.router и t.procedure, то есть ровно ваши router и procedure. А у собранного роутера есть createCaller(ctx) — вызвать процедуру прямо из кода, минуя и сеть, и разбор запроса.

import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';

type Note = { id: number; title: string; archived: boolean };
const rows = new Map<number, Note>([[1, { id: 1, title: 'купить хлеб', archived: false }]]);
let nextId = 2;

// Схема без zod: весь договор — одно свойство «~standard»
const trimmed = {
  '~standard': {
    version: 1 as const,
    vendor: 'свой валидатор',
    // Фантомное поле: в рантайме его нет, но тип входа компилятор читает только отсюда
    types: undefined as unknown as { input: { title: string }; output: { title: string } },
    validate(
      value: unknown,
    ): { value: { title: string }; issues?: undefined } | { issues: { message: string; path: string[] }[] } {
      const title = typeof value === 'object' && value !== null ? (value as { title?: unknown }).title : undefined;
      if (typeof title !== 'string') return { issues: [{ message: 'ожидалась строка', path: ['title'] }] };
      const text = title.trim();
      return text === ''
        ? { issues: [{ message: 'не может быть пустым', path: ['title'] }] }
        : { value: { title: text } };
    },
  },
};

// Точка сборки: отсюда берутся и router, и procedure
const t = initTRPC.create();

export const appRouter = t.router({
  notes: t.router({
    byId: t.procedure.input(z.object({ id: z.number().int().positive() })).query(({ input }) => {
      const note = rows.get(input.id);
      if (!note) throw new TRPCError({ code: 'NOT_FOUND', message: `заметки ${input.id} нет` });
      return note;
    }),
    create: t.procedure.input(z.object({ title: z.string().min(1) })).mutation(({ input }) => {
      const note: Note = { id: nextId++, title: input.title, archived: false };
      rows.set(note.id, note);
      return note;
    }),
    byTitle: t.procedure.input(trimmed).query(({ input }) => {
      const note = [...rows.values()].find((row) => row.title.includes(input.title));
      if (!note) throw new TRPCError({ code: 'NOT_FOUND', message: `нет заметки со словом «${input.title}»` });
      return note;
    }),
  }),
});

export type AppRouter = typeof appRouter;

byId({ id: 1 }) → {"id":1,"title":"купить хлеб","archived":false}
create({ title: "молоко" }) → {"id":2,"title":"молоко","archived":false}
byId({ id: 99 }) → отказ NOT_FOUND | заметки 99 нет
   класс: TRPCError | cause: нет
byId({ id: 0 }) → отказ BAD_REQUEST | id: Too small: expected number to be >0
   класс: TRPCError | cause: ZodError
byTitle({ title: "  хлеб " }) → {"id":1,"title":"купить хлеб","archived":false}
byTitle({ title: "   " }) → отказ BAD_REQUEST | title: не может быть пустым
   класс: TRPCError | cause: StandardSchemaV1Error
notes.byId: query
notes.create: mutation
notes.byTitle: query

Два отказа здесь устроены по-разному, и разница важнее их кодов. NOT_FOUND бросил обработчик — new TRPCError({ code, message }), и cause у него пустой. BAD_REQUEST поставил сам tRPC, до обработчика: вход не прошёл схему. Что обработчик при этом не звался, видно по самому выводу — вызов с нулевым id дошёл бы до rows.get(0) и кончился бы NOT_FOUND, а кончился иначе. Сами коды — доменные, а не статусы HTTP: их у tRPC двадцать один, и в статус каждый переводится отдельно.

Схем в примере две, и t.procedure.input принял обе. Первая — zod, вторая написана в файле руками: весь её договор с tRPC — одно свойство ~standard с функцией validate и фантомным полем типов, тот самый общий язык схем. А классы в cause у них разные, и это не мелочь: getParseFn (@trpc/server 11.18.0) сначала ищет у схемы её собственный разбор — parseAsync, parse, assert, — и только не найдя ни одного, зовёт ~standard.validate и заворачивает исход в свою ошибку. У zod parseAsync есть, поэтому приехал её родной ZodError; у рукописной схемы нет ничего, кроме договора, — и приехал StandardSchemaV1Error самого tRPC. Общий язык здесь не главный, а запасной: он для схем, чьего диалекта tRPC не знает.

Ещё одна строка стоит того, чтобы на неё посмотреть дважды: поиск по слову с пробелами по краям нашёл заметку. До обработчика доехал не исходный вход, а разобранный — тот, что вернула схема. Проверка и приведение здесь одно действие, как и в вашей трубе.

Последние три строки — роутер как значение. appRouter._def.procedures — плоская таблица «полное имя → процедура», собранная из вложенных t.router; вид лежит в _def.type самой процедуры, его пример и печатает. Из неё растёт всё, что делают с роутером снаружи: и проверка «есть ли такая процедура», и описание API. Ту же таблицу вы соберёте руками в третьей задаче.

Отказ схемы и отказ обработчика полезно различать в журнале. Первый значит «клиент прислал не то» и чинится на клиенте; второй значит «данных нет или нельзя» и чинится в предметной области.

tRPC про Nest ничего не знает и знать не должен. Мост между ними один: fastifyTRPCPlugin регистрируется на том самом экземпляре Fastify, который держит адаптер платформы. Приложение при этом остаётся обычным приложением Nest — с модулями, контроллерами и контейнером.

import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';
import type { NotesService } from './notes.service.js';

// Контекст объявляется до create: его тип получают все процедуры этого роутера
export type Ctx = { user: string | null };
const t = initTRPC.context<Ctx>().create();

// Роутер собирается из сервиса, который выдал контейнер Nest
export function makeRouter(notes: NotesService) {
  return t.router({
    notes: t.router({
      byId: t.procedure.input(z.object({ id: z.number().int().positive() })).query(({ input }) => {
        const note = notes.byId(input.id);
        if (!note) throw new TRPCError({ code: 'NOT_FOUND', message: `заметки ${input.id} нет` });
        return note;
      }),
      create: t.procedure
        .input(z.object({ title: z.string().min(1) }))
        .mutation(({ input, ctx }) => notes.create(input.title, ctx.user)),
      mine: t.procedure.query(({ ctx }) => notes.mine(ctx.user)),
    }),
  });
}

export type AppRouter = ReturnType<typeof makeRouter>;

GET /trpc/notes.byId?input={"id":1} → 200 {"result":{"data":{"id":1,"title":"купить хлеб","author":"anya"}}}
GET /trpc/notes.byId?input={"id":99} → 404 NOT_FOUND (404) заметки 99 нет
GET /trpc/notes.byId?input={"id":0} → 400 BAD_REQUEST (400) [ { "origin": "number", "code": "too_small", "minimum": 0, "
POST /trpc/notes.create (x-user: borya) → 200 {"result":{"data":{"id":2,"title":"молоко","author":"borya"}}}
GET /trpc/notes.create?input={"title":"кефир"} → 405 METHOD_NOT_SUPPORTED (405) Unsupported GET-request to mutation procedure at path "notes
POST /trpc/notes.byId → 405 METHOD_NOT_SUPPORTED (405) Unsupported POST-request to query procedure at path "notes.b
GET /trpc/notes.mine → 200 {"result":{"data":[]}}
GET /trpc/notes.mine (x-user: borya) → 200 {"result":{"data":[{"id":2,"title":"молоко","author":"borya"}]}}
GET /trpc/notes.nope?input={} → 404 NOT_FOUND (404) No procedure found on path "notes.nope"
   страж Nest увидел /health
GET /health → 200 {"ok":true}
GET /trpc → 404 {"message":"Cannot GET /trpc","error":"Not Found","statusCode":404}

Сервис процедуры берут у контейнера: makeRouter(app.get(NotesService)). Это ровно тот способ, которым сервис достаётся и контроллеру, и экземпляр получается один и тот же. Транспорта два, предметная область одна: переписывать сервисы под tRPC не приходится — мутация кладёт заметку туда же, откуда её берёт любой контроллер.

Контекст собирается на каждый запрос функцией createContext: сюда приезжает сам запрос, отсюда уезжает объект, который увидят все процедуры. В примере это заголовок x-user, и видно, что он работает: notes.mine без заголовка вернул пустой список, а с заголовком — заметку, которую этот же заголовок минуту назад подписал.

А теперь главное, ради чего прогон и снят. Страж приложения повешен через useGlobalGuards и печатает адрес каждого запроса, который до него дошёл. За одиннадцать запросов он напечатал одну строку, и та про /health. Плагин Fastify стоит на платформе — раньше, чем начинается конвейер Nest, — поэтому ни стражи, ни трубы, ни перехватчики с фильтрами процедур не касаются. Куда в таком случае класть проверку личности и частоты — тема следующей статьи.

Из того же вывода видны и две разные 404. На notes.nope отвечает tRPC: «No procedure found on path» — в таблице процедур такого имени нет. А на голый /trpc отвечает Nest своим «Cannot GET /trpc»: адрес не подошёл плагину, и запрос достался ловушке, которую Nest вешает на платформу для ненайденных маршрутов. Два транспорта — два источника отказа, и по телу ответа всегда видно, чей он.

Правило, которое стоит унести целиком: механизм фреймворка действует ровно там, куда фреймворк успел встать. Плагин, повешенный на платформу, стоит раньше — и весь конвейер проходит мимо него.

Обещание tRPC звучит так: клиент получает типы сервера без единой сгенерированной строки. Проверить его проще всего компилятором. В прогоне ниже клиент знает о сервере одно — import type; ни описания API, ни сгенерированного файла у него нет.

import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';

type Note = { id: number; title: string };
const rows = new Map<number, Note>([[1, { id: 1, title: 'купить хлеб' }]]);
let nextId = 2;

const t = initTRPC.create();

export const appRouter = t.router({
  notes: t.router({
    byId: t.procedure.input(z.object({ id: z.number().int().positive() })).query(({ input }) => {
      const note = rows.get(input.id);
      if (!note) throw new TRPCError({ code: 'NOT_FOUND', message: `заметки ${input.id} нет` });
      return note;
    }),
    create: t.procedure.input(z.object({ title: z.string().min(1) })).mutation(({ input }) => {
      const note: Note = { id: nextId++, title: input.title };
      rows.set(note.id, note);
      return note;
    }),
  }),
});

// На клиент уедет только эта строка: значение роутера остаётся на сервере
export type AppRouter = typeof appRouter;

client.ts(21,22): error TS2322: Type 'string' is not assignable to type 'number'.
client.ts(22,12): error TS2345: Argument of type '"byid"' is not assignable to parameter of type '"byId" | "create"'.
client.ts(23,7): error TS2322: Type 'string' is not assignable to type 'number'.

Три диагностики — три разные стороны договора. Первая: во входе { id: "1" } строка на месте числа, хотя тип входа нигде не объявлен — он выведен из схемы zod, которая стоит в роутере. Вторая: опечатка в имени процедуры, и компилятор перечисляет имена целиком — "byId" | "create". Он их не угадал, это ключи роутера, прочитанные из его типа. Третья: выход обработчика приравняли к числу, и это тоже поймано — inferRouterOutputs достал тип ответа оттуда же.

Код выхода у прогона — 2: это и есть успех примера. Компилятор нашёл три ошибки там, где ни одной строки договора не написано руками.

Транспорт в прогоне свой — чтобы видеть, откуда берутся типы. Настоящий клиент устроен так же, только путь собирает Proxy, а вид вызова стоит последним шагом:

import { createTRPCClient, httpBatchLink } from "@trpc/client";
// тип приезжает обычным импортом типа: при компиляции эта строка исчезает
import type { AppRouter } from "@jsp/api";

export const api = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: "https://api.java-script.pro/trpc" })],
});

async function main() {
  const note = await api.notes.byId.query({ id: 1 });
  const created = await api.notes.create.mutate({ title: "молоко" });
  console.log(note.title, created.id);
}

Значение роутера на клиент не уезжает, и это не аккуратность, а устройство: import type стирается при компиляции, и в бандл попасть нечему. Уехал бы роутер — уехали бы вместе с ним и обработчики, и доступ к базе, и секреты.

Типизированный клиент не защищает сервер. Тип живёт до сборки, а на проводе едет текст, и чужой клиент напишет в нём что угодно. Защищает по-прежнему схема входа.

В apps/api автора процедур двенадцать в двух роутерах, а контроллеров всего два: здоровье и загрузка файла. Написаны процедуры не цепочкой, а декораторами — пакетом nestjs-trpc. Вот выдержка из notes.router.ts, комментарии авторские.

@Router({ alias: 'notes' })
export class NotesRouter {
  constructor(private readonly notesService: NotesService) {}

  // Чтение без AuthMiddleware: лента открыта гостю. Токен, если он есть,
  // разбирает AppContext — от него зависит только видимость своих черновиков,
  // поэтому отклонять запрос без токена не за что.
  @Query({ input: listInput, output: noteListOutput })
  list(@Ctx() ctx: IAppContext, @Input() input: ListInput) {
    return this.notesService.list(input, ctx.userId ?? null);
  }

  // Свои заметки — уже под AuthMiddleware: без токена отвечать нечем,
  // а «свои» для гостя — не пустой список, а ошибка запроса
  @Query({ input: listInput, output: noteListOutput })
  @UseMiddlewares(AuthMiddleware)
  mine(@Ctx() ctx: IAuthedContext, @Input() input: ListInput) {
    return this.notesService.mine(input, ctx.userId);
  }

  // Автор берётся из токена, а не из входа: иначе заметку можно было бы
  // подписать чужим именем
  @Mutation({ input: createNoteInput, output: noteOutput })
  @UseMiddlewares(AuthMiddleware)
  create(@Ctx() ctx: IAuthedContext, @Input() input: CreateNoteInput) {
    return this.notesService.create(ctx.userId, input);
  }

  // … ещё три процедуры: byId, update и remove
}

Узлы всё те же. @Router({ alias: "notes" }) — ветка роутера, та самая t.router({ notes: … }). @Query и @Mutation — вид, объявленный сверху, а не последним шагом цепочки; input и output в их опциях — те же две схемы. @Ctx() и @Input() — параметры обработчика, ровно как @Req() и @Body() у контроллера. А @UseMiddlewares(AuthMiddleware) — то самое звено, которого лишился страж этажом выше.

Плата за декораторы одна, и она крупная: генератор. Из декораторов тип роутера не выводится — они кладут метаданные в рантайме, а компилятору нужен тип во время сборки. Поэтому npx nestjs-trpc generate собирает отдельный файл, где все обработчики — заглушки, и уже его export type AppRouter уезжает на клиент. Этот файл вы видели: им кончалась глава 6.

Вот и весь размен. Цепочка отдаёт тип даром, но пишется не по-нестовски: сервис в процедуру приходится передавать руками, как в прогоне выше. Декораторы возвращают привычный Nest — внедрение через конструктор, звенья на методе, — и требуют шага сборки, который надо не забыть выполнить, и пакета, который надо дождаться. Выбор тут не «лучше — хуже», а «что в вашем проекте ломается громче».

Пакет-посредник между двумя библиотеками живёт на пересечении их версий. Это всегда самое узкое место зависимости — и первое, что стоит посмотреть, прежде чем строить на ней API.