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ê:
strictapanhanulleundefinedantes de chegarem a produção.noUncheckedIndexedAccessobriga a tratarlista[0]como possivelmente inexistente.verbatimModuleSyntaxtorna 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
.enve põe as variáveis emprocess.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 dolistenpermite testar a API sem abrir uma porta.genReqIdcria um identificador por pedido (x-request-id), para ligares a queixa do cliente à linha do log.trustProxydiz de que proxies aceitas o IP original. Sem isto, atrás de um proxy todos os pedidos parecem vir do mesmo IP.coerceTypes: falseevita que"5"seja aceite como5sem 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: falsebloqueia 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.
isseaudimpedem 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
idna 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):
- Procura o token pelo hash, com
SELECT ... FOR UPDATE. - Se já foi usado, revogado ou expirou: revoga toda a família de tokens e devolve 401.
- 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:
- 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. - 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)
- Autenticação e permissões (401, 403, propriedade dos recursos).
- Pagamentos, carteira e reembolsos.
- Concorrência (reservas, saldo, webhooks repetidos).
- Validação das rotas de escrita.
- Erros e cabeçalhos.
- 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
- Alteras
src/db/schema.ts. pnpm db:generatecria o SQL. Opcionalmente dá-lhe um nome:pnpm db:generate --name=add_booking_expiry.- Lê o SQL gerado. Confirma que não apaga colunas ou dados sem querer.
pnpm db:migrateaplica na tua base local.- Fazes commit do
schema.tse da pastadrizzle/, 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 pushem 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 dolisten - ☐
x-request-idem 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-pressureetrustProxyconfigurados
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
isseaud - ☐ 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:resetprotegido - ☐ 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
