ADR: Seleção de Framework

Q: Express 5 vs permanecer no 4?

Express 5 é a versão principal atual com roteamento aprimorado e tratamento de rejeição de promessas. Novos ADRs devem citar Express 5 no Node 24.

Q: Podemos misturar Nest e Fastify?

Nest usa o adaptador Fastify - resultado de ADR válido. Documente a escolha do adaptador nas Notas do Node.js.

Q: Quem assina o ADR?

O líder técnico é o autor; o EM reconhece o impacto na entrega; o arquiteto de plataforma para alinhamento em toda a organização.

Escolher Express 5, Fastify 5 ou NestJS 11 molda a estratégia de contratação, desempenho e testes por anos. Este template de ADR pontua as opções contra restrições mensuráveis da equipe - não religião de framework.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# ADR-NNN: Framework HTTP para <Serviço>
 
## Status
Proposto | Aceito | Superado pelo ADR-XXX
 
## Contexto
- Endpoints: N REST (+ GraphQL?)
- Equipe: M engenheiros, pipeline de contratação
- SLO: latência p95, RPS de pico
- Existente: Monolito Express 4? Pacote de autenticação compartilhado?
 
## Pontuação (1-5, peso entre parênteses)
| Critério | Peso | Express 5 | Fastify 5 | NestJS 11 |
| --- | --- | --- | --- | --- |
| Throughput / latência | 25% | | | |
| Familiaridade da equipe | 20% | | | |
| Estrutura em escala | 20% | | | |
| Ergonomia de testes | 15% | | | |
| Ecossistema / middleware | 10% | | | |
| Custo de migração | 10% | | | |
| **Total ponderado** | | | | |
 
## Decisão
Usaremos <framework> porque <uma frase>.
 
## Consequências
### Positivas
- ...
 
### Negativas
- ...
 
## Gatilho de Revisão
Revisar quando endpoints > X ou p95 exceder Y sob teste de carga.

Quando usar isto:

API Greenfield após prova de conceito
Proposta de migração de Express 4 → 5 ou Express → Fastify
"Devemos usar NestJS para isso?" de um novo EM ou adquirente
Falha no SLO de desempenho atribuída ao framework sem evidências

Exemplo de Trabalho

# ADR-003: Framework HTTP para API de Pedidos
 
## Status
Aceito (2026-07-09)
 
## Contexto
- API de pedidos B2B: 42 endpoints REST, webhooks, sem GraphQL
- Equipe: 6 engenheiros, 4 com experiência em Express, 2 com Nest
- SLO: p95 200ms a 8k RPS de pico; orçamento de erro 99.9%
- Serviço Greenfield; plugin Fastify de autenticação compartilhado `@acme/auth` existe
- Node 24.18.0, TypeScript 5.6, Postgres + Prisma
 
## Pontuação
| Critério | Peso | Express 5 | Fastify 5 | NestJS 11 |
| --- | --- | --- | --- | --- |
| Throughput / latência | 25% | 3 | 5 | 4 |
| Familiaridade da equipe | 20% | 4 | 3 | 3 |
| Estrutura em escala | 20% | 2 | 4 | 5 |
| Ergonomia de testes | 15% | 3 | 5 | 4 |
| Ecossistema | 10% | 5 | 4 | 4 |
| Custo de migração | 10% | 5 | 4 | 3 |
| **Ponderado** | | 3.35 | **4.30** | 3.95 |
 
## Decisão
**Fastify 5** com plugins modulares e o plugin compartilhado `@acme/auth-fastify`.
NestJS rejeitado: sobrecarga de DI injustificada abaixo de 60 endpoints e nenhuma divisão de microsserviços planejada.
 
## Consequências
### Positivas
- Testes `inject()` sem vinculação de porta
- Validação de esquema JSON compilada na inicialização
- Reutilização do plugin de autenticação Fastify interno
 
### Negativas
- Juniores aprendem a curva de encapsulamento de plugins
- Menos respostas no Stack Overflow do que Express
- Contratação: detalhar Fastify na descrição da vaga
 
## Notas do Node.js
- Logging com Pino integrado; alinhar com o SDK OTel da plataforma
- Caminho de migração do Express 5 documentado caso a aquisição force (candidato a superação de ADR)
 
## Gatilho de Revisão
- Contagem de endpoints > 80 OU segunda equipe possuir o mesmo deployable
- p95 > 250ms após ajuste do DB (não culpe o framework primeiro)

O que isso demonstra:

Números forçam a discordância em critérios, não em slogans
Custo de migração ponderado mesmo em greenfield (estratégia de saída)
Gatilho de revisão evita "Aceito" eterno

Análise Profunda

Definições de Critérios

Critério	Medida
Throughput	`autocannon` ou k6 em hello-world + manipulador JSON típico
Estrutura	Módulos sem `app.ts` monstro; módulos Nest vs plugins Fastify
Testes	Velocidade de `inject()` / `supertest`; custo de mock de DI no Nest
Ecossistema	Passport, rate-limit, geradores OpenAPI que você precisa
Migração	Semanas-pessoa da base de código atual

Instantâneos de Framework (Node 24)

Framework	Ponto ideal	Cuidado
Express 5	Familiaridade, vasto middleware	Fácil de construir um monólito não mantenível
Fastify 5	Desempenho, schema-first	Curva de aprendizado de encapsulamento de plugin
NestJS 11	Grandes equipes, monólito modular	Sobrecarga de cold start e DI em APIs minúsculas

Quando o Express Ainda Vence

Adquirente exige Express para integração
Equipe de 2 pessoas, < 15 endpoints, velocidade de chegada ao mercado acima da estrutura
Middleware crítico só existe para Express (verificar antes de assumir)

Quando o Nest Vence

3+ equipes em um único deployable
Microsserviços com múltiplos transportadores planejados
Equipe de Spring/Java espera DI e decoradores

Armadilhas

Benchmark apenas de hello-world - Enganoso. Correção: Faça o benchmark do seu maior manipulador de DTO.
Ignorar pacotes de plataforma compartilhados - Plugin de autenticação interno escolhe o vencedor. Correção: Pontue o ecossistema incluindo bibliotecas internas.
ADR sem gatilho de revisão - Aceito para sempre. Correção: Contagem de endpoints ou limite de SLO.
Framework como band-aid de desempenho - p95 é o DB. Correção: Ajuste o pool antes da migração para Fastify.
Excluir opções rejeitadas - Futuros contratados re-litigam. Correção: Mantenha as pontuações no apêndice do ADR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Hono	Edge + API pequena	Necessidades de DI estilo Nest pesado
tRPC	Monólito TS front+back	Contrato de API REST pública necessário
Apenas Spike, sem ADR	Descartável de 2 semanas	Serviço de produção

FAQs

Express 5 vs permanecer no 4?

Express 5 é a versão principal atual com roteamento aprimorado e tratamento de rejeição de promessas. Novos ADRs devem citar Express 5 no Node 24.

Podemos misturar Nest e Fastify?

Nest usa o adaptador Fastify - resultado de ADR válido. Documente a escolha do adaptador nas Notas do Node.js.

Quem assina o ADR?

O líder técnico é o autor; o EM reconhece o impacto na entrega; o arquiteto de plataforma para alinhamento em toda a organização.

Relacionados

ADR Fastify vs Express - ADR de migração
Checklist de Seleção de Framework - checklist rápido
ADR: Monolito vs Serviços - forma macro
Noções Básicas de Liderança Técnica em Node - propriedade triangular
Melhores Práticas de Liderança Técnica - checklist de liderança

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# ADR-NNN: Framework HTTP para <Serviço>
 
## Status
Proposto | Aceito | Superado pelo ADR-XXX
 
## Contexto
- Endpoints: N REST (+ GraphQL?)
- Equipe: M engenheiros, pipeline de contratação
- SLO: latência p95, RPS de pico
- Existente: Monolito Express 4? Pacote de autenticação compartilhado?
 
## Pontuação (1-5, peso entre parênteses)
| Critério | Peso | Express 5 | Fastify 5 | NestJS 11 |
| --- | --- | --- | --- | --- |
| Throughput / latência | 25% | | | |
| Familiaridade da equipe | 20% | | | |
| Estrutura em escala | 20% | | | |
| Ergonomia de testes | 15% | | | |
| Ecossistema / middleware | 10% | | | |
| Custo de migração | 10% | | | |
| **Total ponderado** | | | | |
 
## Decisão
Usaremos <framework> porque <uma frase>.
 
## Consequências
### Positivas
- ...
 
### Negativas
- ...
 
## Gatilho de Revisão
Revisar quando endpoints > X ou p95 exceder Y sob teste de carga.

Quando usar isto:

API Greenfield após prova de conceito
Proposta de migração de Express 4 → 5 ou Express → Fastify
"Devemos usar NestJS para isso?" de um novo EM ou adquirente
Falha no SLO de desempenho atribuída ao framework sem evidências

Exemplo de Trabalho

# ADR-003: Framework HTTP para API de Pedidos
 
## Status
Aceito (2026-07-09)
 
## Contexto
- API de pedidos B2B: 42 endpoints REST, webhooks, sem GraphQL
- Equipe: 6 engenheiros, 4 com experiência em Express, 2 com Nest
- SLO: p95 200ms a 8k RPS de pico; orçamento de erro 99.9%
- Serviço Greenfield; plugin Fastify de autenticação compartilhado `@acme/auth` existe
- Node 24.18.0, TypeScript 5.6, Postgres + Prisma
 
## Pontuação
| Critério | Peso | Express 5 | Fastify 5 | NestJS 11 |
| --- | --- | --- | --- | --- |
| Throughput / latência | 25% | 3 | 5 | 4 |
| Familiaridade da equipe | 20% | 4 | 3 | 3 |
| Estrutura em escala | 20% | 2 | 4 | 5 |
| Ergonomia de testes | 15% | 3 | 5 | 4 |
| Ecossistema | 10% | 5 | 4 | 4 |
| Custo de migração | 10% | 5 | 4 | 3 |
| **Ponderado** | | 3.35 | **4.30** | 3.95 |
 
## Decisão
**Fastify 5** com plugins modulares e o plugin compartilhado `@acme/auth-fastify`.
NestJS rejeitado: sobrecarga de DI injustificada abaixo de 60 endpoints e nenhuma divisão de microsserviços planejada.
 
## Consequências
### Positivas
- Testes `inject()` sem vinculação de porta
- Validação de esquema JSON compilada na inicialização
- Reutilização do plugin de autenticação Fastify interno
 
### Negativas
- Juniores aprendem a curva de encapsulamento de plugins
- Menos respostas no Stack Overflow do que Express
- Contratação: detalhar Fastify na descrição da vaga
 
## Notas do Node.js
- Logging com Pino integrado; alinhar com o SDK OTel da plataforma
- Caminho de migração do Express 5 documentado caso a aquisição force (candidato a superação de ADR)
 
## Gatilho de Revisão
- Contagem de endpoints > 80 OU segunda equipe possuir o mesmo deployable
- p95 > 250ms após ajuste do DB (não culpe o framework primeiro)

O que isso demonstra:

Números forçam a discordância em critérios, não em slogans
Custo de migração ponderado mesmo em greenfield (estratégia de saída)
Gatilho de revisão evita "Aceito" eterno

Análise Profunda

Definições de Critérios

Critério	Medida
Throughput	`autocannon` ou k6 em hello-world + manipulador JSON típico
Estrutura	Módulos sem `app.ts` monstro; módulos Nest vs plugins Fastify
Testes	Velocidade de `inject()` / `supertest`; custo de mock de DI no Nest
Ecossistema	Passport, rate-limit, geradores OpenAPI que você precisa
Migração	Semanas-pessoa da base de código atual

Instantâneos de Framework (Node 24)

Framework	Ponto ideal	Cuidado
Express 5	Familiaridade, vasto middleware	Fácil de construir um monólito não mantenível
Fastify 5	Desempenho, schema-first	Curva de aprendizado de encapsulamento de plugin
NestJS 11	Grandes equipes, monólito modular	Sobrecarga de cold start e DI em APIs minúsculas

Quando o Express Ainda Vence

Adquirente exige Express para integração
Equipe de 2 pessoas, < 15 endpoints, velocidade de chegada ao mercado acima da estrutura
Middleware crítico só existe para Express (verificar antes de assumir)

Quando o Nest Vence

3+ equipes em um único deployable
Microsserviços com múltiplos transportadores planejados
Equipe de Spring/Java espera DI e decoradores

Armadilhas

Benchmark apenas de hello-world - Enganoso. Correção: Faça o benchmark do seu maior manipulador de DTO.
Ignorar pacotes de plataforma compartilhados - Plugin de autenticação interno escolhe o vencedor. Correção: Pontue o ecossistema incluindo bibliotecas internas.
ADR sem gatilho de revisão - Aceito para sempre. Correção: Contagem de endpoints ou limite de SLO.
Framework como band-aid de desempenho - p95 é o DB. Correção: Ajuste o pool antes da migração para Fastify.
Excluir opções rejeitadas - Futuros contratados re-litigam. Correção: Mantenha as pontuações no apêndice do ADR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Hono	Edge + API pequena	Necessidades de DI estilo Nest pesado
tRPC	Monólito TS front+back	Contrato de API REST pública necessário
Apenas Spike, sem ADR	Descartável de 2 semanas	Serviço de produção

FAQs

Express 5 vs permanecer no 4?

Express 5 é a versão principal atual com roteamento aprimorado e tratamento de rejeição de promessas. Novos ADRs devem citar Express 5 no Node 24.

Podemos misturar Nest e Fastify?

Nest usa o adaptador Fastify - resultado de ADR válido. Documente a escolha do adaptador nas Notas do Node.js.

Quem assina o ADR?

O líder técnico é o autor; o EM reconhece o impacto na entrega; o arquiteto de plataforma para alinhamento em toda a organização.

Relacionados

ADR Fastify vs Express - ADR de migração
Checklist de Seleção de Framework - checklist rápido
ADR: Monolito vs Serviços - forma macro
Noções Básicas de Liderança Técnica em Node - propriedade triangular
Melhores Práticas de Liderança Técnica - checklist de liderança

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

ADR: Seleção de Framework

Buscar na documentação

ADR: Seleção de Framework