Tipagem de Handlers Express/Fastify

Handlers HTTP type-safe capturam formas incorretas de body, params e query em tempo de compilação - combine genéricos do Express 5 e inferência de schema do Fastify 5 com validação em tempo de execução nas fronteiras.

Receita

// Express 5 - body tipado via genérico (após middleware de validação)
import type { Request, Response } from 'express';
 
interface CreateUserBody { email: string; name: string }
 
export async function createUser(
  req: Request<unknown, unknown, CreateUserBody>,
  res: Response,
): Promise<void> {
  res.status(201).json({ id: '1', ...req.body });
}

// Fastify 5 - tipos orientados por schema
import Fastify from 'fastify';
 
const app = Fastify();
 
app.post<{ Body: { email: string } }>('/users', async (req, reply) => {
  return reply.code(201).send({ id: '1', email: req.body.email });
});

Quando usar isso:

• APIs CRUD com formas de parâmetros repetidas (id, paginação)
• Middleware de autenticação anexando userId a requisições
• Utilitários de handler compartilhados entre roteadores
• Prevenção de erros de digitação em req.body.foo antes do tempo de execução

Exemplo de Trabalho

// express-app.d.ts - aumento
import 'express-serve-static-core';
 
declare module 'express-serve-static-core' {
  interface Request {
    userId?: string;
  }
}

// auth-middleware.ts
import type { Request, Response, NextFunction } from 'express';
 
export function requireAuth(req: Request, res: Response, next: NextFunction): void {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    res.status(401).json({ error: 'unauthorized' });
    return;
  }
  req.userId = 'user-123';
  next();
}

// fastify-route.ts
import Fastify from 'fastify';
import { z } from 'zod';
 
const app = Fastify();
 
const CreateUser = z.object({ email: z.string().email(), name: z.string().min(1) });
 
app.post('/users', {
  schema: {
    body: {
      type: 'object',
      required: ['email', 'name'],
      properties: { email: { type: 'string' }, name: { type: 'string' } },
    },
  },
}, async (req, reply) => {
  const body = CreateUser.parse(req.body);
  return reply.code(201).send({ id: '1', ...body });
});

O que isso demonstra:

• Aumento do Express adiciona userId com tipagem adequada em todos os handlers
• Middleware deve chamar next() ou encerrar a resposta - NextFunction tipado para erros
• Schema JSON do Fastify valida em tempo de execução; Zod adiciona regras mais rigorosas (formato de email)
• Parse após a validação do schema para regras complexas que schemas Express/Fastify não conseguem expressar

Mergulho Profundo

Como Funciona

• Express usa genéricos Request<P, ResBody, ReqBody, ReqQuery, Locals> - raramente todos preenchidos manualmente; aumento para campos transversais.
• Fastify infere tipos do schema ao usar as const ou TypeBox - ponte Zod via fastify-type-provider-zod.
• Tipagem de Resposta - res.json<T>() não é imposto em tempo de execução - ainda valide DTOs de saída para APIs públicas.
• Middleware de Erro - Express (err, req, res, next); Fastify setErrorHandler com erros tipados.

Padrões de Tipagem de Handler

Notas TypeScript

import type { FastifyRequest, FastifyReply } from 'fastify';
 
type AuthedRequest = FastifyRequest & { userId: string };
 
function getUserId(req: FastifyRequest): string {
  return (req as AuthedRequest).userId;
}

Prefira plugins/decoradores (fastify.decorateRequest) em vez de casts quando possível.

Armadilhas

• Confiar em req.body sem validação - tipos mentem em tempo de execução. Correção: parse Zod na fronteira conforme Zod nas Fronteiras.
• Request excessivamente genérico em todo lugar - any vaza via padrões. Correção: tipos de handler por rota ou alias AppRequest compartilhado.
• Versão de tipos Express incompatível - @types/express deve corresponder ao Express 5. Correção: alinhe versões em package.json.
• Schema Fastify e Zod divergentes - duas fontes de verdade. Correção: gere JSON Schema a partir de Zod ou use type provider.
• Tipagem de middleware assíncrono - retornar Promise rejeitada sem next(err) no Express. Correção: envolva utilitários de middleware assíncrono.

Alternativas

FAQs

Relacionados

• Zod nas Fronteiras - validação em tempo de execução
• Básico do Express - padrões do Express 5
• Básico do Fastify - configuração do Fastify 5
• Compartilhando Tipos com Frontend - pacotes DTO

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.