YepAPI/skills

Express y Fastify

Reglas

• Organizar las rutas por dominio: routes/users.ts, routes/orders.ts — un enrutador por recurso
• Validar todas las entradas con Zod: analizar req.body, req.params, req.query antes de procesar
• Manejador de errores centralizado: middleware de captura total (Express) o setErrorHandler (Fastify)
• Devolver un formato de error consistente: { error: { code: string, message: string, details?: unknown } }
• TypeScript: tipificar solicitud/respuesta con genéricos — Request<Params, ResBody, ReqBody, Query>
• Orden del middleware: CORS, analizador de cuerpo, autenticación, limitación de tasa, rutas, manejador de errores
• Usar manejadores de ruta asíncronos — envolver con captura de errores o usar express-async-errors
• Fastify: usar el sistema de plugins para encapsular rutas y decoradores — fastify.register()
• Esquemas de Fastify: definir JSON Schema o usar @fastify/type-provider-zod para validación + serialización
• Health check: GET /health — devolver 200 con estado de conectividad a DB/Redis
• Apagado graceful: escuchar SIGTERM, dejar de aceptar conexiones, finalizar solicitudes en curso

Patrones

// Express + validación Zod
import { Router } from "express";
import { z } from "zod";

const router = Router();
const CreateUserSchema = z.object({ email: z.string().email(), name: z.string().min(1) });

router.post("/users", async (req, res, next) => {
  try {
    const body = CreateUserSchema.parse(req.body);
    const user = await createUser(body);
    res.status(201).json(user);
  } catch (err) { next(err); }
});

// Fastify + Type Provider Zod
import Fastify from "fastify";
import { serializerCompiler, validatorCompiler, ZodTypeProvider } from "fastify-type-provider-zod";

const app = Fastify().withTypeProvider<ZodTypeProvider>();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.post("/users", { schema: { body: CreateUserSchema } }, async (req) => {
  return createUser(req.body); // completamente tipificado
});

Evitar

• Poner lógica de negocio en los manejadores de ruta — extraer a la capa de servicio/dominio
• Olvidar el manejo de errores asíncrono en Express — las promesas no capturadas detienen el proceso
• Importar todas las rutas en un solo archivo — usar router.use() o plugins de Fastify para modularidad
• Saltar la validación de entrada porque "el frontend valida" — siempre validar en el lado del servidor