TypeScript Academy · Aula

Middleware e Contexto

Adicione autenticação e contexto compartilhado aos procedimentos.

Middleware e Contexto é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 4 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.

O que é o contexto

Cada requisição tRPC carrega um contexto: dados compartilhados disponíveis para todos os procedimentos, como o client do banco de dados, a requisição e o usuário atual. Você o cria uma vez por requisição com uma função createContext.

export async function createContext({ req }: { req: Request }) {
  const token = req.headers.get('authorization');
  const user = await getUserFromToken(token);
  return { user };
}

Tipando o contexto

O tRPC infere o tipo do contexto a partir de createContext e o transmite a todos os procedimentos. Você inicializa a instância com esse tipo de contexto para que os resolvedores vejam ctx tipado corretamente.

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

type Context = Awaited<ReturnType<typeof createContext>>;
const t = initTRPC.context<Context>().create();

Lendo ctx em um resolvedor

Dentro de qualquer procedimento, o contexto fica disponível como ctx e é totalmente tipado. Aqui, um procedimento lê o usuário atual a partir do contexto.

const me = t.procedure.query(({ ctx }) => {
  // ctx.user is typed from createContext
  return ctx.user;
});

O que é middleware

O middleware é executado antes do resolvedor de um procedimento. Ele pode verificar permissões, registrar eventos ou modificar o contexto. Ele chama next() para continuar ou lança uma exceção para rejeitar a requisição.

const logger = t.middleware(async ({ path, next }) => {
  console.log('calling', path);
  return next();
});

Um middleware de autenticação

Um middleware comum aplica a autenticação. Se não houver um usuário no contexto, ele lança um erro UNAUTHORIZED; caso contrário, continua até o resolvedor.

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

const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next();
});

Restringindo o contexto na sequência

O middleware pode refinar o tipo do contexto passando um novo ctx para next. Depois da verificação de autenticação, a presença do usuário é garantida, portanto restringimos user de possivelmente nulo para não nulo.

const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { user: ctx.user } }); // user now non-null
});

Construindo um procedimento protegido

Conecte o middleware com .use para criar um procedimento protegido reutilizável. Qualquer procedimento criado a partir dele exige autenticação e vê um usuário não nulo.

export const protectedProcedure = t.procedure.use(isAuthed);

const secret = protectedProcedure.query(({ ctx }) => {
  return 'Hello ' + ctx.user.name; // user is guaranteed
});

Público versus protegido

Agora você tem dois blocos de construção: publicProcedure para pontos de acesso abertos e protectedProcedure para os autenticados. Escolher a base correta documenta e aplica o acesso tanto no nível dos tipos quanto no nível de execução.

const ping = publicProcedure.query(() => 'pong');
const account = protectedProcedure.query(({ ctx }) => ctx.user);

Propagação tipada do contexto

O contexto restringido se propaga: como protectedProcedure garantiu ctx.user, todo resolvedor criado a partir dele vê o tipo não nulo sem precisar verificar novamente. O middleware codifica essa garantia uma única vez.

// In any protectedProcedure resolver:
// ctx.user is User, not User | null

Compondo middleware

O middleware é composto encadeando .use. Você pode aplicar primeiro o registro de eventos, depois a autenticação e, em seguida, uma verificação de permissões por função. Cada etapa é executada em ordem e pode restringir ainda mais o contexto para a próxima.

const adminProcedure = protectedProcedure.use(({ ctx, next }) => {
  if (ctx.user.role !== 'admin') {
    throw new TRPCError({ code: 'FORBIDDEN' });
  }
  return next();
});

A visão completa

O contexto fornece dados por requisição, o middleware os protege e refina, e os procedimentos especializados incorporam essas garantias. Combinando isso com esquemas de entrada e um client tipado, você obtém uma API segura em tempo de execução e em tempo de compilação, de ponta a ponta.

// createContext -> ctx
// middleware -> auth + narrowing
// protectedProcedure -> guaranteed ctx.user
// typed client -> end-to-end safety

Verificação rápida

Teste sua compreensão de contexto e middleware.

Recapitulação

Você protegeu uma API tRPC com contexto e middleware.

createContext cria dados compartilhados por requisição, tipados por meio de initTRPC.context.
O middleware é executado antes dos resolvedores para proteger e refinar o contexto.
Passar ctx para next restringe seu tipo.
protectedProcedure incorpora a autenticação, para que os resolvedores recebam um usuário não nulo.

Você concluiu o curso de segurança de tipos de ponta a ponta.

Perguntas Frequentes

A aula “Middleware e Contexto” é grátis?

Sim — o texto completo de “Middleware e Contexto” é 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 “Middleware e Contexto”?

Adicione autenticação e contexto compartilhado aos procedimentos. 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 4 de 4.

Quanto tempo leva a aula “Middleware e Contexto”?

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