srsaiombo

Construindo uma API sénior com TypeScript e Node.js, passo a passo

Guia passo a passo para construir uma API sénior com TypeScript e Node.js. Cada biblioteca (Fastify, TypeBox, Drizzle, JWT, Argon2, Redis, Vitest e mais) explicada: o que é, como usar e porquê. Sem projecto para clonar, só o raciocínio e o código essencial.

Imagem de capa: Construindo uma API sénior com TypeScript e Node.js, passo a passo

Este tutorial é um guia para qualquer pessoa, mesmo para quem sente muita dificuldade. Mas atenção: se estás mesmo a começar, estás no sítio errado. Recomendo que comeces pelo YouTube. Aqui é para quem já manja um pouco de TypeScript e, mesmo assim, vai ter de se esforçar. O que importa não é o repositório, é a ordem em que as peças entram e o porquê de cada uma.

Isto é um guia, não um projecto para clonar. Copia os blocos, adapta aos teus nomes e lê o "Porquê" de cada passo, que é a parte que não aparece nos tutoriais.

Termos rápidos: backend é a parte do sistema que o utilizador não vê (guarda dados, faz contas, decide o que é permitido). API é a porta por onde o site ou a app falam com ele. Middleware/plugin é uma peça que se encaixa no servidor para lhe dar uma capacidade nova.


Parte 1: Preparar o terreno

Passo 1: Iniciar o projecto (Node.js, pnpm, TypeScript)

O que é: Node.js corre JavaScript no servidor. TypeScript acrescenta tipos, que o compilador verifica antes de o código correr. pnpm é o gestor de pacotes: rápido e com instalações reprodutíveis (pnpm-lock.yaml).

Instalar e usar:

mkdir minha-api && cd minha-api
pnpm init
pnpm add -D typescript tsx @types/node

No package.json, activa ESM e cria os scripts:

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "typecheck": "tsc --noEmit"
  }
}

O tsx corre TypeScript directamente em desenvolvimento. Em produção, compila-se com tsc e corre-se JavaScript puro.

Porquê: com type: module usas o mesmo sistema de módulos (import) do navegador. E com o pnpm a instalação é igual na tua máquina, no servidor e no Docker.

Passo 2: tsconfig.json em modo estrito

O que é: o ficheiro que diz ao compilador o quão rigoroso deve ser.

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"],
  "exclude": ["src/**/__tests__"]
}

Com NodeNext, os imports relativos terminam em .js, mesmo que o ficheiro seja .ts:

import { env } from './config/env.js';

Porquê:

  • strict apanha null e undefined antes de chegarem a produção.
  • noUncheckedIndexedAccess obriga a tratar lista[0] como possivelmente inexistente.
  • verbatimModuleSyntax torna explícito o que é import de tipo e o que é import de código.

Passo 3: Biome (lint)

O que é: um verificador de estilo e erros comuns. É rápido e já traz o formatador.

pnpm add -D @biomejs/biome
pnpm biome init

Script: "lint": "biome check .".

Porquê: o código fica com um estilo único, sem discussões, e os erros evidentes (variáveis não usadas, comparações perigosas) aparecem logo.

Passo 4: dotenv + TypeBox, a configuração que falha cedo

O que é:

  • dotenv lê o ficheiro .env e põe as variáveis em process.env.
  • TypeBox descreve a forma dos dados e valida-os.
pnpm add dotenv typebox
// src/config/env.ts
import 'dotenv/config';
import { Type, type Static } from 'typebox';
import Value from 'typebox/value';

const EnvSchema = Type.Object({
  NODE_ENV: Type.Union([
    Type.Literal('development'),
    Type.Literal('test'),
    Type.Literal('production'),
  ]),
  PORT: Type.String({ minLength: 1 }),
  DATABASE_URL: Type.String({ minLength: 1 }),
  JWT_SECRET: Type.String({ minLength: 32 }),
  CORS_ORIGINS: Type.String({ minLength: 1 }),
  TRUSTED_PROXIES: Type.String({ minLength: 1 }),
});

export type Env = Static<typeof EnvSchema>;

function load(): Env {
  const raw = {
    NODE_ENV: process.env.NODE_ENV ?? 'development',
    PORT: process.env.PORT ?? '3001',
    DATABASE_URL: process.env.DATABASE_URL,
    JWT_SECRET: process.env.JWT_SECRET,
    CORS_ORIGINS: process.env.CORS_ORIGINS,
    TRUSTED_PROXIES: process.env.TRUSTED_PROXIES,
  };

  let env: Env;
  try {
    env = Value.Parse(EnvSchema, raw);
  } catch {
    console.error('Configuração inválida: confirma o .env');
    process.exit(1);
  }

  if (env.NODE_ENV === 'production') {
    if (env.JWT_SECRET.startsWith('replace-')) {
      console.error('JWT_SECRET ainda é o valor de exemplo');
      process.exit(1);
    }
    if (!env.CORS_ORIGINS.split(',').every((o) => o.startsWith('https://'))) {
      console.error('Em produção, todas as origens CORS têm de ser https://');
      process.exit(1);
    }
  }
  return env;
}

export const env = load();

Porquê: é melhor a aplicação recusar-se a arrancar às 9h, com uma mensagem clara, do que descobrir às 3h da manhã que produção corria com a chave de exemplo. Isto chama-se fail-fast.


Parte 2: O servidor

Passo 5: Fastify, a base da API

O que é: o framework HTTP. Dá-te rotas, hooks (código que corre antes ou depois de um pedido), plugins e validação integrada.

pnpm add fastify
// src/app.ts
import Fastify from 'fastify';
import { randomUUID } from 'node:crypto';
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
import { env } from './config/env.js';

export async function buildApp() {
  const app = Fastify({
    logger: env.NODE_ENV !== 'test',
    genReqId: () => randomUUID(),
    trustProxy: env.TRUSTED_PROXIES.split(','),
    ajv: {
      customOptions: {
        removeAdditional: false,
        coerceTypes: false,
        useDefaults: true,
        allErrors: true,
      },
    },
  }).withTypeProvider<TypeBoxTypeProvider>();

  app.addHook('onSend', async (req, reply) => {
    reply.header('x-request-id', req.id);
  });

  app.get('/health', async () => ({ status: 'ok' }));

  return app;
}
// src/server.ts
import { buildApp } from './app.js';
import { env } from './config/env.js';

const app = await buildApp();
await app.listen({ port: Number(env.PORT), host: '0.0.0.0' });

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.on(signal, async () => {
    await app.close();
    process.exit(0);
  });
}

Porquê:

  • buildApp() separado do listen permite testar a API sem abrir uma porta.
  • genReqId cria um identificador por pedido (x-request-id), para ligares a queixa do cliente à linha do log.
  • trustProxy diz de que proxies aceitas o IP original. Sem isto, atrás de um proxy todos os pedidos parecem vir do mesmo IP.
  • coerceTypes: false evita que "5" seja aceite como 5 sem avisar.
  • O shutdown gracioso deixa os pedidos em curso acabarem antes de desligar.

Passo 6: Erros de negócio e handler global

O que é: uma classe para erros esperados e um único sítio que decide o que o cliente vê.

// src/exceptions/app-error.ts
export class AppError extends Error {
  constructor(message: string, public readonly statusCode = 400) {
    super(message);
  }
}

Em buildApp(), antes de devolver app:

import { AppError } from './exceptions/app-error.js';

app.setErrorHandler((err, req, reply) => {
  if (err instanceof AppError) {
    return reply.status(err.statusCode).send({ error: err.message });
  }
  if (err.validation) {
    return reply.status(400).send({ error: 'Dados inválidos' });
  }
  req.log.error(err);
  return reply.status(500).send({ error: 'Erro interno' });
});

Porquê: o utilizador percebe o que correu mal (AppError('Sem lugares', 409)), mas um erro inesperado sai genérico, sem stack trace, sem nome de tabela. O detalhe fica só no log.

Passo 7: TypeBox + @fastify/type-provider-typebox, o contrato de cada rota

O que é: o schema que descreve o que cada rota aceita e devolve. O type provider faz o TypeScript inferir os tipos de body, query e params a partir desse schema.

pnpm add @fastify/type-provider-typebox
// src/modules/bookings/booking.schema.ts
import { Type } from 'typebox';

export const CreateBookingBody = Type.Object(
  {
    routeId: Type.String({ minLength: 1, maxLength: 40 }),
    seats: Type.Integer({ minimum: 1, maximum: 6 }),
    paymentMethod: Type.Union([Type.Literal('WALLET'), Type.Literal('MULTICAIXA')]),
  },
  { additionalProperties: false },
);

export const BookingResponse = Type.Object({
  id: Type.String(),
  status: Type.String(),
  totalKz: Type.Integer(),
});
// src/modules/bookings/booking.routes.ts
import type { FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox';
import { CreateBookingBody, BookingResponse } from './booking.schema.js';

export const bookingRoutes: FastifyPluginAsyncTypebox = async (app) => {
  app.post(
    '/bookings',
    {
      schema: {
        tags: ['bookings'],
        body: CreateBookingBody,
        response: { 201: BookingResponse },
      },
    },
    async (req, reply) => {
      const { routeId, seats } = req.body; // tipos inferidos
      // ...chamar o service
      return reply.status(201).send({ id: 'x', status: 'PENDING', totalKz: seats * 1000 });
    },
  );
};

Porquê:

  • Um só schema dá-te validação, tipos e documentação.
  • additionalProperties: false bloqueia mass assignment: campos extra que alteram colunas que não devias expor.
  • Validar também a resposta impede que uma coluna sensível (como o hash da password) saia por engano.

Passo 8: @fastify/swagger + @fastify/swagger-ui, documentação automática

O que é: o primeiro gera o contrato OpenAPI a partir dos teus schemas. O segundo mostra-o numa página interactiva (/docs).

pnpm add @fastify/swagger @fastify/swagger-ui
import swagger from '@fastify/swagger';
import swaggerUi from '@fastify/swagger-ui';

await app.register(swagger, {
  openapi: {
    info: { title: 'Minha API', version: '1.0.0' },
    components: {
      securitySchemes: {
        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      },
    },
  },
});
await app.register(swaggerUi, { routePrefix: '/docs' });

Regista o swagger antes das rotas.

Porquê: a documentação nasce do código, por isso nunca fica desactualizada. Em produção, avalia se /docs deve estar público ou protegido.

Passo 9: fastify-plugin, para os plugins partilharem contexto

O que é: por omissão, o Fastify encapsula cada plugin: o que registas lá dentro (decorators, hooks) não é visto lá fora. O fastify-plugin retira essa encapsulação.

pnpm add fastify-plugin
import fp from 'fastify-plugin';

export default fp(async (app) => {
  app.decorate('exemplo', () => 'olá');
}, { name: 'exemplo' });

Porquê: sem ele, o app.authenticate que crias num plugin de autenticação não existiria nas rotas dos outros módulos.


Parte 3: Fechar a porta

Passo 10: @fastify/helmet, cabeçalhos de segurança

O que é: o servidor envia, em cada resposta, instruções de segurança ao navegador. O Helmet activa as principais, como a CSP (de onde se podem carregar scripts) e a HSTS (usar sempre HTTPS).

pnpm add @fastify/helmet
import helmet from '@fastify/helmet';
await app.register(helmet);

Porquê: mitiga XSS, clickjacking e downgrade para HTTP com uma linha. Se usares o Swagger UI, pode ser preciso ajustar a CSP nessa rota.

Passo 11: @fastify/cors, quem pode chamar a tua API a partir de um site

O que é: os navegadores aplicam a Same-Origin Policy: um site só lê respostas de outra origem (esquema + domínio + porta) se essa origem o autorizar. O CORS é essa autorização. Antes de pedidos "não simples", o navegador envia um preflight (OPTIONS).

pnpm add @fastify/cors
import cors from '@fastify/cors';

await app.register(cors, {
  origin: env.CORS_ORIGINS.split(','), // lista explícita
  credentials: true,
});

Porquê: com uma lista de origens permitidas, um site malicioso não consegue usar o navegador da vítima para chamar a tua API. Nunca uses * em produção. E atenção: o CORS protege o navegador, não a API. Não substitui a autenticação.

Passo 12: @fastify/rate-limit, limite de pedidos

O que é: limita quantos pedidos cada cliente pode fazer numa janela de tempo.

pnpm add @fastify/rate-limit
import rateLimit from '@fastify/rate-limit';

await app.register(rateLimit, { max: 100, timeWindow: '1 minute' });

Mais apertado numa rota sensível:

app.post('/auth/login', {
  config: { rateLimit: { max: 5, timeWindow: '1 minute' } },
  // ...schema
}, handler);

Porquê: trava força bruta no login, scraping e abuso. Por omissão o contador vive em memória: com várias réplicas deixa de ser partilhado, e aí precisas de Redis.

Passo 13: @fastify/under-pressure, proteger o servidor quando está sobrecarregado

O que é: mede o atraso do event loop, a memória (heap, RSS) e devolve 503 quando passa dos limites.

pnpm add @fastify/under-pressure
import underPressure from '@fastify/under-pressure';

await app.register(underPressure, {
  maxEventLoopDelay: 1000,
  maxHeapUsedBytes: 1_000_000_000,
  maxRssBytes: 1_500_000_000,
  retryAfter: 10,
});

Porquê: é melhor recusar alguns pedidos com um 503 do que deixar o processo morrer e levar todos consigo. Ajusta os números à memória do teu servidor.


Parte 4: Dados

Passo 14: pg + Drizzle ORM, a base de dados

O que é:

  • PostgreSQL é a base de dados.
  • pg é o driver que fala com ela (e gere um pool de ligações reutilizáveis).
  • Drizzle é o ORM: escreves o schema em TypeScript e as queries ficam tipadas, mas perto do SQL.
pnpm add drizzle-orm pg
pnpm add -D drizzle-kit @types/pg
// src/db/schema.ts
import { pgTable, pgEnum, text, integer, timestamp, index } from 'drizzle-orm/pg-core';

export const bookingStatus = pgEnum('booking_status', [
  'PENDING', 'CONFIRMED', 'IN_PROGRESS', 'COMPLETED', 'CANCELLED',
]);

export const bookings = pgTable(
  'bookings',
  {
    id: text('id').primaryKey(),
    routeId: text('route_id').notNull(),
    passengerId: text('passenger_id').notNull(),
    seats: integer('seats').notNull(),
    totalKz: integer('total_kz').notNull(), // dinheiro em inteiros
    status: bookingStatus('status').notNull().default('PENDING'),
    createdAt: timestamp('created_at', { precision: 3 }).notNull().defaultNow(),
  },
  (t) => [index('bookings_route_idx').on(t.routeId)],
);
// src/config/database.ts
import pg from 'pg';
import { drizzle } from 'drizzle-orm/node-postgres';
import * as schema from '../db/schema.js';
import { env } from './env.js';

export const pool = new pg.Pool({ connectionString: env.DATABASE_URL, max: 10 });
export const db = drizzle({ client: pool, schema });

Porquê:

  • Valores monetários em inteiros (Kwanzas) evitam erros de arredondamento dos decimais.
  • Os índices aceleram as pesquisas mais frequentes.
  • O Drizzle dá-te SQL explícito e controlo sobre transacções e locks, sem esconder o que corre na base de dados.

Passo 15: drizzle-kit, migrações versionadas

O que é: gera ficheiros SQL a partir das alterações ao schema e aplica-os por ordem.

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/db/schema.ts',
  out: './drizzle',
  dbCredentials: { url: process.env.DATABASE_URL! },
});

Scripts: "db:generate": "drizzle-kit generate", "db:migrate": "drizzle-kit migrate", "db:studio": "drizzle-kit studio".

Porquê: as alterações à base de dados ficam em ficheiros no Git, revistas como o resto do código. Nunca alteres produção à mão.

Passo 16: Concorrência, a regra que evita overbooking

O que é: duas pessoas a reservar o último lugar ao mesmo tempo. Sem cuidado, as duas ganham.

Como usar: uma transacção para o que mexe em várias tabelas, e um update condicional (só muda se o estado ainda for o que leste):

import { and, eq } from 'drizzle-orm';
import { db } from '../../config/database.js';
import { bookings } from '../../db/schema.js';
import { AppError } from '../../exceptions/app-error.js';

export async function confirmBooking(id: string) {
  const updated = await db
    .update(bookings)
    .set({ status: 'CONFIRMED' })
    .where(and(eq(bookings.id, id), eq(bookings.status, 'PENDING')))
    .returning({ id: bookings.id });

  if (updated.length === 0) {
    throw new AppError('A reserva já mudou de estado', 409);
  }
}

Quando precisas de ler e depois alterar com segurança (lugares, saldo), usa db.transaction com .for('update') na leitura, que bloqueia a linha até a transacção terminar.

Porquê: só um pedido ganha, o outro recebe um 409 Conflict com mensagem clara. E repara que isto também torna a operação idempotente: repetir o mesmo pedido não estraga nada.


Parte 5: Identidade

Passo 17: argon2 e bcryptjs, passwords

O que é: nunca se guarda a password, guarda-se o hash (uma impressão digital que não se inverte). Argon2id é o algoritmo recomendado: lento e exigente em memória, o que torna caro o ataque offline. bcryptjs serve para continuar a validar hashes antigos.

pnpm add argon2 bcryptjs
// src/modules/auth/password-security.ts
import argon2 from 'argon2';
import bcrypt from 'bcryptjs';

export const hashPassword = (password: string) =>
  argon2.hash(password, { type: argon2.argon2id });

// hash falso, calculado uma vez, para igualar o tempo quando o email não existe
const DUMMY_HASH = await argon2.hash('dummy-password', { type: argon2.argon2id });

export async function verifyPassword(password: string, hash: string | null) {
  if (!hash) {
    await argon2.verify(DUMMY_HASH, password).catch(() => false);
    return false;
  }
  if (hash.startsWith('$2')) return bcrypt.compare(password, hash); // legado
  return argon2.verify(hash, password);
}

Porquê: se a base de dados for roubada, as passwords não ficam à vista. O hash falso faz com que o tempo de resposta não revele que emails têm conta (user enumeration). E acrescenta um limite de tentativas de login (por exemplo, 10 falhas em 15 minutos), com rate limit ou Redis.

Passo 18: @fastify/jwt, o access token

O que é: o JWT é um token assinado que transporta claims (sub = quem é, role = que papel tem). O servidor valida a assinatura sem consultar a base de dados em cada pedido. Pensa numa pulseira de festival: quem a tem, entra, durante pouco tempo.

pnpm add @fastify/jwt
// src/plugins/auth.plugin.ts
import fp from 'fastify-plugin';
import jwt from '@fastify/jwt';
import type { FastifyReply, FastifyRequest } from 'fastify';
import { env } from '../config/env.js';

type Role = 'DRIVER' | 'PASSENGER';

declare module '@fastify/jwt' {
  interface FastifyJWT {
    payload: { sub: string; role: Role };
    user: { sub: string; role: Role };
  }
}
declare module 'fastify' {
  interface FastifyInstance {
    authenticate: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
  }
}

export default fp(async (app) => {
  await app.register(jwt, {
    secret: env.JWT_SECRET,
    sign: { expiresIn: '15m', iss: 'minha-api', aud: 'minha-api-clientes' },
    verify: { allowedIss: 'minha-api', allowedAud: 'minha-api-clientes' },
  });

  app.decorate('authenticate', async (req: FastifyRequest, reply: FastifyReply) => {
    try {
      await req.jwtVerify();
    } catch {
      reply.code(401).send({ error: 'Não autenticado' });
    }
  });
}, { name: 'auth' });

Autorização por papel e uso numa rota:

// src/plugins/role-guard.ts
import type { FastifyReply, FastifyRequest } from 'fastify';

export const requireRoles =
  (...roles: Array<'DRIVER' | 'PASSENGER'>) =>
  async (req: FastifyRequest, reply: FastifyReply) => {
    if (!roles.includes(req.user.role)) {
      return reply.code(403).send({ error: 'Sem permissão' });
    }
  };
app.get('/driver/routes', {
  onRequest: [app.authenticate, requireRoles('DRIVER')],
}, handler);

Para emitir o token depois do login: app.jwt.sign({ sub: user.id, role: user.role }).

Porquê:

  • Vida curta (15 minutos): um token roubado serve pouco tempo.
  • iss e aud impedem reutilizar tokens emitidos para outro serviço.
  • Autenticação diz quem és (401 se falhar). Autorização diz o que podes fazer (403 se falhar). E o papel não chega: no service, confirma também a propriedade (só o dono da rota confirma o pagamento dessa rota). Esquecer isto dá IDOR: um utilizador autenticado mexe em dados de outro só trocando o id na URL.

Passo 19: Refresh token com rotação (Node crypto)

O que é: um segundo token, de longa duração, que serve só para pedir um access token novo. Não é preciso biblioteca, o módulo crypto do Node chega.

import { randomBytes, createHash } from 'node:crypto';

const token = randomBytes(32).toString('base64url'); // vai para o cliente
const tokenHash = createHash('sha256').update(token).digest('hex'); // vai para a base de dados

Fluxo da rotação (dentro de uma transacção):

  1. Procura o token pelo hash, com SELECT ... FOR UPDATE.
  2. Se já foi usado, revogado ou expirou: revoga toda a família de tokens e devolve 401.
  3. Senão, marca-o como usado e emite um novo na mesma família.

Porquê: na base de dados só existe o hash, por isso uma fuga não dá sessões. E a reutilização de um token antigo é sinal de roubo: derrubar toda a família tira a sessão a quem o roubou (e obriga o utilizador legítimo a fazer login outra vez, o que é o mal menor).


Parte 6: Extras que fazem diferença

Passo 20: ioredis, cache que não pode derrubar a API

O que é: Redis guarda dados em memória, muito rápido. O ioredis é o cliente.

pnpm add ioredis
// src/utils/cache.helper.ts
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379', {
  lazyConnect: true,
  maxRetriesPerRequest: 1,
});
redis.on('error', () => {}); // a cache nunca derruba a API

export async function cached<T>(key: string, ttlSeconds: number, load: () => Promise<T>): Promise<T> {
  try {
    const hit = await redis.get(key);
    if (hit) return JSON.parse(hit) as T;
  } catch {
    /* falha da cache = cache miss */
  }
  const value = await load();
  try {
    await redis.set(key, JSON.stringify(value), 'EX', ttlSeconds);
  } catch {
    /* ignora */
  }
  return value;
}

Porquê: este padrão chama-se cache-aside: lês da cache, se falhar vais à base de dados e preenches a cache. Se o Redis cair, a API fica mais lenta, não fica parada. Quando os dados mudam, apaga a chave (redis.del).

Passo 21: @fastify/multipart, uploads

O que é: lê ficheiros enviados em multipart/form-data.

pnpm add @fastify/multipart
import multipart from '@fastify/multipart';
import { randomUUID } from 'node:crypto';
import { writeFile } from 'node:fs/promises';

await app.register(multipart, { limits: { fileSize: 10 * 1024 * 1024, files: 1 } });

app.post('/uploads', { onRequest: [app.authenticate] }, async (req, reply) => {
  const file = await req.file();
  if (!file) return reply.code(400).send({ error: 'Ficheiro em falta' });

  const allowed = ['image/jpeg', 'image/png', 'application/pdf'];
  if (!allowed.includes(file.mimetype)) {
    return reply.code(415).send({ error: 'Tipo de ficheiro não permitido' });
  }

  const name = `${randomUUID()}.bin`; // nome gerado por ti, nunca o do cliente
  await writeFile(`./storage/private/${name}`, await file.toBuffer());
  return reply.code(201).send({ id: name });
});

Porquê: o limite de tamanho evita ficheiros gigantes, o nome gerado por ti evita path traversal, e separar private/ de public/ garante que comprovativos nunca são servidos a toda a gente. O mimetype vem do cliente e pode ser falso: para dados sensíveis, confirma também o conteúdo do ficheiro.

Passo 22: Vitest, testes que protegem o que custa caro

O que é: o Vitest é o motor de testes (rápido, com TypeScript nativo). Com app.inject() simulas pedidos HTTP sem abrir portas, por isso os testes são rápidos e estáveis. O @vitest/coverage-v8 mede que linhas do código os testes percorrem.

pnpm add -D vitest @vitest/coverage-v8

Scripts: "test": "vitest run", "test:watch": "vitest" e "test:coverage": "vitest run --coverage".

22.1 Configuração

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    include: ['src/**/*.test.ts'],
    setupFiles: ['./src/__tests__/setup.ts'],
    coverage: {
      provider: 'v8',
      include: ['src/**'],
      exclude: ['src/**/__tests__/**'],
    },
  },
});

O setup.ts define o ambiente de teste antes de o env.ts ser carregado (lembra-te: ele faz process.exit se a configuração for inválida):

// src/__tests__/setup.ts
process.env.NODE_ENV = 'test';
process.env.JWT_SECRET = 'x'.repeat(40);
process.env.CORS_ORIGINS = 'http://localhost:3000';
process.env.TRUSTED_PROXIES = '127.0.0.1';
process.env.DATABASE_URL ??= 'postgres://postgres:postgres@localhost:5432/minha_api_test';

Porquê: testes nunca devem usar a base de dados nem os segredos reais. Usa uma base de testes separada (ou PGlite) e variáveis próprias.

22.2 Um helper para criar tokens

// src/__tests__/helpers.ts
import type { FastifyInstance } from 'fastify';

export const tokenFor = (
  app: FastifyInstance,
  role: 'DRIVER' | 'PASSENGER',
  sub = 'user-1',
) => app.jwt.sign({ sub, role });

export const auth = (token: string) => ({ authorization: `Bearer ${token}` });

Assim não precisas de fazer login em cada teste.

22.3 Autenticação e permissões

// src/__tests__/auth-guard.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import type { FastifyInstance } from 'fastify';
import { buildApp } from '../app.js';
import { tokenFor, auth } from './helpers.js';

let app: FastifyInstance;
beforeAll(async () => { app = await buildApp(); });
afterAll(async () => { await app.close(); });

describe('autenticação e permissões', () => {
  it('sem token devolve 401', async () => {
    const res = await app.inject({ method: 'GET', url: '/driver/routes' });
    expect(res.statusCode).toBe(401);
  });

  it('token inválido devolve 401', async () => {
    const res = await app.inject({
      method: 'GET',
      url: '/driver/routes',
      headers: auth('isto-nao-e-um-jwt'),
    });
    expect(res.statusCode).toBe(401);
  });

  it('passageiro não acede a rota de condutor (403)', async () => {
    const res = await app.inject({
      method: 'GET',
      url: '/driver/routes',
      headers: auth(tokenFor(app, 'PASSENGER')),
    });
    expect(res.statusCode).toBe(403);
  });

  it('condutor acede à sua rota (200)', async () => {
    const res = await app.inject({
      method: 'GET',
      url: '/driver/routes',
      headers: auth(tokenFor(app, 'DRIVER')),
    });
    expect(res.statusCode).toBe(200);
  });
});

O que isto protege: a diferença entre 401 (não sei quem és) e 403 (sei quem és, mas não podes). É o teste mais barato e o que evita mais desastres.

22.4 Validação (o contrato)

// src/__tests__/validation.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import type { FastifyInstance } from 'fastify';
import { buildApp } from '../app.js';
import { tokenFor, auth } from './helpers.js';

let app: FastifyInstance;
beforeAll(async () => { app = await buildApp(); });
afterAll(async () => { await app.close(); });

const post = (payload: unknown) =>
  app.inject({
    method: 'POST',
    url: '/bookings',
    headers: auth(tokenFor(app, 'PASSENGER')),
    payload: payload as object,
  });

describe('validação de POST /bookings', () => {
  it('rejeita lugares fora do intervalo', async () => {
    const res = await post({ routeId: 'r1', seats: 0, paymentMethod: 'WALLET' });
    expect(res.statusCode).toBe(400);
  });

  it('rejeita tipos errados (sem coerção silenciosa)', async () => {
    const res = await post({ routeId: 'r1', seats: '2', paymentMethod: 'WALLET' });
    expect(res.statusCode).toBe(400);
  });

  it('rejeita campos extra (mass assignment)', async () => {
    const res = await post({
      routeId: 'r1',
      seats: 1,
      paymentMethod: 'WALLET',
      totalKz: 1, // o cliente não pode escolher o preço
    });
    expect(res.statusCode).toBe(400);
  });
});

O que isto protege: o additionalProperties: false e o coerceTypes: false que configuraste. Se alguém os alterar sem querer, estes testes falham.

22.5 Erros: nada de segredos para o cliente

// src/__tests__/errors.test.ts
import { describe, it, expect } from 'vitest';
import { buildApp } from '../app.js';

describe('tratamento de erros', () => {
  it('erro inesperado devolve 500 genérico, sem detalhes', async () => {
    const app = await buildApp();
    app.get('/boom', async () => {
      throw new Error('falha na tabela users: password_hash');
    });

    const res = await app.inject({ method: 'GET', url: '/boom' });

    expect(res.statusCode).toBe(500);
    expect(res.json()).toEqual({ error: 'Erro interno' });
    expect(res.body).not.toContain('password_hash');
    await app.close();
  });

  it('todas as respostas trazem x-request-id', async () => {
    const app = await buildApp();
    const res = await app.inject({ method: 'GET', url: '/health' });
    expect(res.headers['x-request-id']).toBeTruthy();
    await app.close();
  });
});

Regista a rota /boom antes do primeiro inject, porque depois de a app arrancar já não se adicionam rotas.

O que isto protege: information disclosure. Garante que um erro interno nunca vaza nomes de tabelas ou stack traces.

22.6 Passwords (teste unitário, sem HTTP)

// src/modules/auth/__tests__/password-security.test.ts
import { describe, it, expect } from 'vitest';
import { hashPassword, verifyPassword } from '../password-security.js';

describe('passwords', () => {
  it('aceita a password certa e rejeita a errada', async () => {
    const hash = await hashPassword('Segredo#2026');
    expect(await verifyPassword('Segredo#2026', hash)).toBe(true);
    expect(await verifyPassword('errada', hash)).toBe(false);
  });

  it('nunca guarda a password em claro', async () => {
    const hash = await hashPassword('Segredo#2026');
    expect(hash).not.toContain('Segredo');
    expect(hash.startsWith('$argon2id$')).toBe(true);
  });

  it('email inexistente (sem hash) devolve false sem rebentar', async () => {
    expect(await verifyPassword('qualquer', null)).toBe(false);
  });
});

O que isto protege: garante que o algoritmo é mesmo Argon2id e que o caminho do "utilizador inexistente" não quebra.

22.7 Concorrência (o teste que separa sénior de júnior)

Este precisa de base de dados. Dispara dois pedidos ao mesmo tempo e verifica que só um ganha:

// src/modules/bookings/__tests__/booking-concurrency.test.ts
import { describe, it, expect } from 'vitest';
import { confirmBooking } from '../booking.service.js';
// helper teu: cria uma reserva PENDING na base de testes
import { createPendingBooking } from '../../../__tests__/factories.js';

describe('confirmação de reservas em concorrência', () => {
  it('só uma de duas confirmações simultâneas tem sucesso', async () => {
    const booking = await createPendingBooking();

    const results = await Promise.allSettled([
      confirmBooking(booking.id),
      confirmBooking(booking.id),
    ]);

    const ok = results.filter((r) => r.status === 'fulfilled');
    const failed = results.filter((r) => r.status === 'rejected');

    expect(ok).toHaveLength(1);
    expect(failed).toHaveLength(1);
    expect((failed[0] as PromiseRejectedResult).reason.statusCode).toBe(409);
  });
});

Faz o mesmo para o último lugar de uma rota (dois passageiros, um lugar livre) e para webhooks repetidos (o mesmo aviso de pagamento enviado duas vezes tem de creditar uma só vez).

O que isto protege: overbooking e crédito duplicado. Se alguém tirar o update condicional ou o lock, este teste fica vermelho.

22.8 Base de dados nos testes

Duas opções, por ordem de simplicidade:

  1. Base de dados de teste (PostgreSQL local ou no Docker), com as migrações aplicadas uma vez antes de tudo (globalSetup) e as tabelas limpas entre testes.
  2. PGlite em memória: PostgreSQL embebido, sem instalar nada.
// src/__tests__/global-setup.ts
import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { db, pool } from '../config/database.js';

export default async function () {
  await migrate(db, { migrationsFolder: './drizzle' });
  return async () => { await pool.end(); };
}

Regista-o em vitest.config.ts com test: { globalSetup: ['./src/__tests__/global-setup.ts'] }. Mantém os testes independentes: cada um cria os seus dados (factories) e nenhum depende da ordem de outro.

22.9 O que testar primeiro (por ordem de prejuízo)

  1. Autenticação e permissões (401, 403, propriedade dos recursos).
  2. Pagamentos, carteira e reembolsos.
  3. Concorrência (reservas, saldo, webhooks repetidos).
  4. Validação das rotas de escrita.
  5. Erros e cabeçalhos.
  6. O resto.

22.10 Cobertura e CI

pnpm test:coverage mostra que linhas ficaram por testar. Um limiar de cobertura obriga a equipa a não deixar cair o nível:

coverage: {
  provider: 'v8',
  thresholds: { lines: 70, functions: 70 },
}

Porquê: cobertura não prova qualidade (podes percorrer uma linha sem verificar nada), mas mostra onde não estás a olhar. E sem CI (um pipeline que corre lint, typecheck, test e build em cada alteração), os testes só protegem quando alguém se lembra de os correr.

Porquê Vitest, no geral: é rápido, entende TypeScript sem configuração extra e o app.inject evita portas e servidores reais. Testa primeiro o que custa dinheiro ou dados se falhar.

Passo 23: PGlite, PostgreSQL embebido para desenvolver

O que é: o PGlite é um PostgreSQL que corre dentro do Node, sem instalar nada. O pglite-socket expõe-no pelo protocolo normal do PostgreSQL, para a tua app ligar-se como a um servidor real.

pnpm add -D @electric-sql/pglite @electric-sql/pglite-socket

Porquê: quem entra no projecto corre pnpm dev sem instalar PostgreSQL nem Docker. Serve para desenvolvimento local, não para produção.

Passo 24: Docker, o ambiente que nasce sempre igual

O que é: empacota a API e as dependências numa imagem que corre igual em qualquer máquina.

FROM node:24-alpine AS build
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:24-alpine
WORKDIR /app
RUN corepack enable
ENV NODE_ENV=production
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod
COPY --from=build /app/dist ./dist
COPY drizzle ./drizzle
USER node
CMD ["sh", "-c", "node dist/migrate.js && node dist/server.js"]

O migrate.js aplica as migrações no arranque:

// src/migrate.ts
import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { db, pool } from './config/database.js';

await migrate(db, { migrationsFolder: './drizzle' });
await pool.end();

Porquê: duas fases (build e runtime) deixam a imagem final pequena, sem ferramentas de desenvolvimento. USER node evita correr como root. E migrar no arranque garante que a base de dados está sempre à altura do código. Com várias réplicas, corre as migrações num passo único do deploy.

Passo 25: Scripts de migrações e de testes

O que é: em vez de decorares comandos, pões tudo no package.json. Quem entra no projecto corre pnpm check e sabe se está tudo bem.

25.1 O package.json completo

{
  "packageManager": "[email protected]",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "typecheck": "tsc --noEmit",
    "lint": "biome check .",

    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:migrate:prod": "node dist/migrate.js",
    "db:check": "drizzle-kit check",
    "db:studio": "drizzle-kit studio",
    "db:seed": "tsx scripts/seed.ts",
    "db:reset": "tsx scripts/reset-db.ts && pnpm db:migrate && pnpm db:seed",

    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:db:up": "docker compose -f docker-compose.test.yml up -d --wait",
    "test:db:down": "docker compose -f docker-compose.test.yml down -v",
    "test:ci": "pnpm test:db:up && pnpm test:coverage; pnpm test:db:down",

    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build"
  }
}

Muda o número da versão em packageManager para a do teu pnpm (pnpm -v). O CI usa esse campo para instalar a versão certa.

O que cada um faz:

Script Quando usar
db:generate Depois de alterares schema.ts. Gera um novo ficheiro SQL em drizzle/.
db:migrate Em desenvolvimento, aplica as migrações pendentes.
db:migrate:prod No servidor e no Docker. Corre o JavaScript compilado, sem drizzle-kit.
db:check Verifica se as migrações estão consistentes entre si (útil no CI).
db:studio Abre o Drizzle Studio para ver os dados no navegador.
db:seed Cria os dados iniciais, de forma idempotente.
db:reset Apaga tudo, volta a migrar e a semear. Só em ambiente local.
check Corre lint, tipos, testes e build antes de fazeres commit.

Porquê: o db:migrate usa drizzle-kit (ferramenta de desenvolvimento). Em produção não instalas dependências de desenvolvimento, por isso existe o db:migrate:prod, que usa só o drizzle-orm.

25.2 Migrações: o fluxo de trabalho

  1. Alteras src/db/schema.ts.
  2. pnpm db:generate cria o SQL. Opcionalmente dá-lhe um nome: pnpm db:generate --name=add_booking_expiry.
  3. Lê o SQL gerado. Confirma que não apaga colunas ou dados sem querer.
  4. pnpm db:migrate aplica na tua base local.
  5. Fazes commit do schema.ts e da pasta drizzle/, os dois juntos.

Regras que poupam dores de cabeça:

  • Nunca edites uma migração que já correu noutro ambiente. Cria uma nova.
  • Nunca uses drizzle-kit push em produção. Ele altera a base de dados sem deixar histórico.
  • Apagar uma coluna em produção faz-se em duas migrações: primeiro o código deixa de a usar, depois a coluna é removida.

Em drizzle.config.ts, garante que o .env é lido:

import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/db/schema.ts',
  out: './drizzle',
  dbCredentials: { url: process.env.DATABASE_URL! },
});

25.3 Script de migração para produção

// src/migrate.ts
import { migrate } from 'drizzle-orm/node-postgres/migrator';
import { db, pool } from './config/database.js';

try {
  await migrate(db, { migrationsFolder: './drizzle' });
  console.log('Migrações aplicadas');
} catch (error) {
  console.error('Falha na migração', error);
  process.exitCode = 1; // faz o deploy falhar, em vez de arrancar com a base desactualizada
} finally {
  await pool.end();
}

No Docker, o CMD do passo anterior (node dist/migrate.js && node dist/server.js) só arranca a API se a migração tiver sucesso, graças ao &&.

25.4 Seed idempotente

// scripts/seed.ts
import { db, pool } from '../src/config/database.js';
import { platformSettings } from '../src/db/schema.js'; // adapta à tua tabela

await db
  .insert(platformSettings)
  .values({ id: 'default', feeRate: 15 })
  .onConflictDoNothing();

console.log('Seed concluído');
await pool.end();

Porquê idempotente: correr o seed duas vezes dá o mesmo resultado que correr uma. Assim podes recriar ambientes de demonstração e de QA sem medo. O seed cria só dados de configuração. O primeiro administrador real cria-se com um script próprio (admin:bootstrap) que lê a password do ambiente, nunca de um ficheiro no repositório.

25.5 Reset da base de dados (só local)

// scripts/reset-db.ts
import 'dotenv/config';
import pg from 'pg';

const url = process.env.DATABASE_URL ?? '';
const host = url ? new URL(url).hostname : '';

if (process.env.NODE_ENV === 'production' || !['localhost', '127.0.0.1'].includes(host)) {
  console.error('Recusado: o reset só corre em localhost e fora de produção.');
  process.exit(1);
}

const pool = new pg.Pool({ connectionString: url });
await pool.query('DROP SCHEMA IF EXISTS public CASCADE');
await pool.query('DROP SCHEMA IF EXISTS drizzle CASCADE'); // histórico de migrações
await pool.query('CREATE SCHEMA public');
await pool.end();
console.log('Base de dados reposta');

Porquê as duas guardas: um comando que apaga tudo tem de ser impossível de correr por engano contra produção. Se o host não for local, ele recusa.

25.6 Base de dados para os testes (Docker)

# docker-compose.test.yml
services:
  postgres-test:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: minha_api_test
    ports:
      - "5433:5432"
    tmpfs:
      - /var/lib/postgresql/data   # em memória: mais rápido, desaparece ao parar
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d minha_api_test"]
      interval: 2s
      timeout: 3s
      retries: 15

O --wait do test:db:up espera pelo healthcheck, por isso os testes só começam quando a base está pronta.

Ficheiro .env.test (não leva segredos reais):

NODE_ENV=test
DATABASE_URL=postgres://postgres:postgres@localhost:5433/minha_api_test
JWT_SECRET=um-segredo-so-para-testes-com-mais-de-32-chars
CORS_ORIGINS=http://localhost:3000
TRUSTED_PROXIES=127.0.0.1

Actualiza o setup.ts para o carregar (funciona em Windows, Linux e macOS, sem cross-env):

// src/__tests__/setup.ts
import { config } from 'dotenv';

config({ path: '.env.test', override: true });

Porquê: as variáveis de teste ficam num ficheiro, não espalhadas por scripts, e os testes nunca tocam na tua base de desenvolvimento.

25.7 Limpar os dados entre testes

// src/__tests__/db-helpers.ts
import { sql } from 'drizzle-orm';
import { db } from '../config/database.js';

export async function resetTables() {
  await db.execute(sql`
    TRUNCATE TABLE bookings, payments, wallet_transactions
    RESTART IDENTITY CASCADE
  `);
}

Usa-o no teste: beforeEach(async () => { await resetTables(); });. Lista as tuas tabelas reais. O CASCADE apaga também as que dependem delas.

Porquê: cada teste começa de um estado conhecido e nenhum depende do resultado de outro.

25.8 Pipeline de CI (GitHub Actions)

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17-alpine
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: minha_api_test
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U postgres"
          --health-interval 5s
          --health-timeout 5s
          --health-retries 10
    env:
      NODE_ENV: test
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/minha_api_test
      JWT_SECRET: um-segredo-so-para-testes-com-mais-de-32-chars
      CORS_ORIGINS: http://localhost:3000
      TRUSTED_PROXIES: 127.0.0.1
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm db:check
      - run: pnpm test:coverage
      - run: pnpm build

Como as variáveis do CI são definidas no ambiente, o config({ override: true }) do setup.ts só as substitui se existir um .env.test no repositório. Escolhe um dos dois caminhos e mantém-no.

Porquê: o CI corre lint, tipos, consistência das migrações, testes com uma base de dados real e build em cada alteração. É o que faz os testes protegerem mesmo quando ninguém se lembra de os correr.

25.9 Rotina diária

pnpm test:db:up        # liga a base de testes
pnpm test:watch        # testes em modo contínuo enquanto programas
pnpm check             # antes de cada commit
pnpm test:db:down      # desliga e apaga a base de testes

Resumo das bibliotecas

Biblioteca Para que serve Porquê
fastify Servidor HTTP Rápido, com hooks, plugins e schemas
typebox + @fastify/type-provider-typebox Schemas, tipos e validação Um schema, três usos
@fastify/swagger + swagger-ui Documentação OpenAPI Nunca desactualizada
fastify-plugin Partilhar decorators entre plugins Sem isto, o authenticate não é visto
@fastify/helmet Cabeçalhos de segurança CSP, HSTS, anti-XSS
@fastify/cors Origens permitidas Lista explícita, nunca *
@fastify/rate-limit Limite de pedidos Trava abuso e força bruta
@fastify/under-pressure Protecção contra sobrecarga 503 em vez de crash
pg + drizzle-orm + drizzle-kit Base de dados e migrações SQL explícito, tipos, histórico
argon2 + bcryptjs Passwords Argon2id novo, bcrypt legado
@fastify/jwt Access token Curto, com iss e aud
ioredis Cache Opcional, tolerante a falhas
@fastify/multipart Uploads Limites e validação
dotenv Variáveis de ambiente Config fora do código
vitest + @vitest/coverage-v8 Testes e cobertura Rápido, com app.inject
typescript + tsx + @biomejs/biome Tipos, execução e lint Erros apanhados cedo

Checklist rápido

Marca o que já tens.

Preparar

  • ☐ pnpm, ESM e scripts (dev, build, typecheck, test)
  • ☐ TypeScript strict e Biome
  • ☐ Configuração validada com falha no arranque

Servidor

  • ☐ buildApp() separado do listen
  • ☐ x-request-id em cada resposta
  • ☐ Handler global de erros (500 genérico)
  • ☐ Schemas TypeBox em body, query, params e resposta
  • ☐ Swagger em /docs (decide se é público em produção)

Perímetro

  • ☐ Helmet activo
  • ☐ CORS com lista de origens https://
  • ☐ Rate limit global e apertado no login
  • ☐ under-pressure e trustProxy configurados

Dados

  • ☐ Drizzle com migrações versionadas
  • ☐ Dinheiro em inteiros e índices nas pesquisas
  • ☐ Updates condicionais e transacções onde há disputa

Identidade

  • ☐ Argon2id, hash falso anti-timing e limite de tentativas
  • ☐ JWT curto com iss e aud
  • ☐ Refresh token com rotação (só o hash guardado)
  • ☐ Papéis (RBAC) e verificação de propriedade

Entrega

  • ☐ Cache que falha em silêncio
  • ☐ Uploads validados, privados separados dos públicos
  • ☐ Testes de login, permissões, pagamentos e concorrência
  • ☐ Base de testes separada, tabelas limpas entre testes
  • ☐ Scripts de migração, seed idempotente e db:reset protegido
  • ☐ CI a correr lint, tipos, db:check, testes e build
  • ☐ Docker em duas fases, a correr como node

Para terminar

Não precisas de usar tudo no primeiro dia. Começa pelo Fastify, pelo schema e pela configuração validada, e vai juntando as peças quando o problema aparecer. O que muda de um júnior para um sénior é saber porque cada peça está lá.

Menos pânico, mais diagnóstico.

— Orlando Saiombo

Achaste útil?

Leva esta ideia contigo.

Novidades sem ruído

A próxima ideia
chega à tua caixa.

Recebe um email quando sair um novo artigo. Sem frequência inventada e podes cancelar quando quiseres.

Só usamos o email para enviar novidades do blogue.