Express & Fastify
Regras
- Organize rotas por domínio:
routes/users.ts, routes/orders.ts — um roteador por recurso
- Valide toda entrada com Zod: analise
req.body, req.params, req.query antes de processar
- Manipulador de erro centralizado: middleware "catch-all" (Express) ou
setErrorHandler (Fastify)
- Retorne formato de erro consistente:
{ error: { code: string, message: string, details?: unknown } }
- TypeScript: tipar requisição/resposta com genéricos —
Request<Params, ResBody, ReqBody, Query>
- Ordem dos middlewares: CORS, body parser, autenticação, rate limiting, rotas, manipulador de erro
- Use handlers de rota assíncronos — envolva com captura de erros ou use
express-async-errors
- Fastify: use o sistema de plugins para encapsular rotas e decoradores —
fastify.register()
- Fastify schemas: defina JSON Schema ou use
@fastify/type-provider-zod para validação + serialização
- Health check:
GET /health — retorne 200 com status de conectividade do banco/Redis
- Desligamento gracioso: ouça SIGTERM, pare de aceitar conexões, finalize requisições em andamento
Padrões
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); }
});
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);
});
Evite
- Colocar lógica de negócio em handlers de rota — extraia para camada de serviço/domínio
- Esquecer o tratamento de erro assíncrono no Express — rejeições não tratadas quebram o processo
- Importar todas as rotas em um único arquivo — use
router.use() ou plugins do Fastify para modularidade
- Pular validação de entrada porque "o frontend valida" — sempre valide no lado do servidor