TypeScript Academy · Aula

Definindo Roteadores e Procedimentos

Crie consultas e mutações com validação de entrada.

Definindo Roteadores e Procedimentos é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.

Inicializando o tRPC

Todo back-end tRPC começa com a criação de uma instância usando initTRPC. Ela retorna construtores para roteadores e procedimentos. Normalmente, você a cria uma vez e exporta as partes necessárias.

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

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

Um primeiro procedimento

Um procedimento é um único ponto de acesso da API. O mais simples é uma query que retorna um valor. publicProcedure.query define um ponto de acesso de leitura sem entrada.

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

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

Validando a entrada

Os procedimentos declaram sua entrada com um validador, normalmente um esquema zod. .input(schema) valida em tempo de execução e também infere o tipo da entrada para o resolvedor e para o client.

import { z } from 'zod';

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

Lendo a entrada

Dentro do resolvedor, a entrada validada fica disponível como input e é totalmente tipada a partir do esquema. Não há conversão manual; zod e tRPC inferem a estrutura em conjunto.

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

Operações mutation

Use .mutation para operações que alteram dados. A estrutura é igual à de uma query, mas sinaliza uma escrita, o que afeta o armazenamento em cache do client e o método HTTP.

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

Construindo o roteador da aplicação

Reúna os procedimentos em um roteador passando um objeto para router(...). Cada chave se torna o nome de um procedimento chamável. Esse appRouter é toda a sua API.

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

Roteadores aninhados

Os roteadores podem ser aninhados para organizar APIs grandes. Um valor no objeto do roteador também pode ser um roteador, produzindo chamadas com espaço de nomes, como user.byId.

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

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

Exportando o tipo do roteador

A exportação mais importante é o tipo do roteador. O client o importará para obter segurança de tipos completa. Exporte o valor para o adaptador do servidor e o tipo para o client.

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

Conectando um adaptador

Para disponibilizar o roteador por HTTP, conecte um adaptador. O tRPC fornece adaptadores para Node independente, Express, Next.js, Fetch e outros. O adaptador transforma requisições recebidas em chamadas de procedimentos.

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

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

Organizando os arquivos

Uma organização comum é: um trpc.ts com initTRPC e o router/publicProcedure exportado, roteadores de funcionalidades em seus próprios arquivos e um appRouter raiz que os compõe. Manter initTRPC em um único lugar evita várias instâncias.

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

Recapitulando a inferência da entrada

Como .input(schema) valida e infere ao mesmo tempo, você escreve o esquema uma vez e obtém uma proteção em tempo de execução e um tipo estático. O client verá exatamente a entrada esperada por cada procedimento, derivada desses esquemas.

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

Verificação rápida

Teste sua compreensão de roteadores e procedimentos.

Recapitulação

Você construiu um back-end tRPC.

initTRPC.create() produz os construtores router e procedure.
.input(schema) valida e infere a entrada.
.query lê; .mutation escreve.
Componha procedimentos em appRouter e exporte type AppRouter = typeof appRouter.

Próximo: consumir a API com um client totalmente tipado.

Perguntas Frequentes

A aula “Definindo Roteadores e Procedimentos” é grátis?

Sim — o texto completo de “Definindo Roteadores e Procedimentos” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.

O que vou aprender em “Definindo Roteadores e Procedimentos”?

Crie consultas e mutações com validação de entrada. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar TypeScript Academy?

Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Definindo Roteadores e Procedimentos”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de TypeScript Academy?

Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

A Arquitetura tRPC
Definindo Roteadores e Procedimentos
Inferência de Tipos entre Cliente e Servidor
Middleware e Contexto

← Voltar para TypeScript Academy