Tipado de manejadores de Express/Fastify

Los manejadores HTTP con seguridad de tipos detectan formas incorrectas de body, params y query en tiempo de compilación; combina los genéricos de Express 5 y la inferencia de esquemas de Fastify 5 con la validación en tiempo de ejecución en los límites.

Receta

// Express 5 - cuerpo tipado a través de genérico (después del middleware de validación)
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 impulsados por esquemas
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 });
});

Cuándo usarlo:

• APIs CRUD con formas de parámetros repetidas (id, paginación)
• Middleware de autenticación que adjunta userId a las solicitudes
• Utilidades de manejadores compartidas entre enrutadores
• Prevenir errores tipográficos de req.body.foo antes del tiempo de ejecución

Ejemplo de trabajo

// 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 });
});

Lo que esto demuestra:

• El aumento de Express añade userId con tipado adecuado en todos los manejadores
• El middleware debe llamar a next() o finalizar la respuesta - NextFunction tipada para errores
• El esquema JSON de Fastify valida en tiempo de ejecución; Zod añade reglas más estrictas (formato de correo electrónico)
• Analizar después de la validación del esquema para reglas complejas que los esquemas de Express/Fastify no pueden expresar

Análisis profundo

Cómo funciona

• Express utiliza genéricos Request<P, ResBody, ReqBody, ReqQuery, Locals> - rara vez se rellenan todos manualmente; aumento para campos transversales.
• Fastify infiere tipos del schema cuando se usa as const o TypeBox - puente Zod a través de fastify-type-provider-zod.
• Tipado de respuesta - res.json<T>() no se aplica en tiempo de ejecución - aún valida los DTOs de salida para las APIs públicas.
• Middleware de errores - Express (err, req, res, next); Fastify setErrorHandler con errores tipados.

Patrones de tipado de manejadores

Notas de TypeScript

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

Prefiere plugins/decoradores (fastify.decorateRequest) sobre las conversiones de tipo cuando sea posible.

Errores comunes

• Confiar en req.body sin validación - los tipos mienten en tiempo de ejecución. Solución: análisis Zod en el límite según Zod en los límites.
• Request demasiado genérico en todas partes - any se filtra a través de los valores predeterminados. Solución: tipos de manejadores por ruta o alias AppRequest compartido.
• Versión de tipos de Express no coincidente - @types/express debe coincidir con Express 5. Solución: alinear versiones en package.json.
• Desfase entre el esquema de Fastify y Zod - dos fuentes de verdad. Solución: generar el esquema JSON a partir de Zod o usar un proveedor de tipos.
• Tipado de middleware asíncrono - devolver una Promesa rechazada sin next(err) en Express. Solución: envolver las utilidades de middleware asíncronas.

Alternativas

Preguntas frecuentes

Relacionado

• Zod en los límites - validación en tiempo de ejecución
• Conceptos básicos de Express - patrones de Express 5
• Conceptos básicos de Fastify - configuración de Fastify 5
• Compartir tipos con el frontend - paquetes DTO

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.