Boas Práticas de Arquitetura

Otimize para isolamento de mudanças, não para distribuição prematura. Estas práticas mantêm os backends Node.js evoluíveis sem a sobrecarga de microsserviços desde o primeiro dia.

Como Usar Esta Lista

• Trate itens não verificados como débito de arquitetura - priorize a tier A antes de novos recursos
• Revise após marcos importantes: escala Series B, escopo PCI ou divisão de squad
• Emparelhe com Checklist de Refatoração trimestralmente
• Atribua um proprietário por regra de limite de módulo, não "a equipe"

A - Comece Simples, Mantenha-se Evoluível

• Padrão para um monólito modular. Um único deploy com módulos de recursos é melhor do que cinco serviços que ninguém consegue depurar em plantão. Reavalie quando o bloqueio de implantação for medido.
• Empacote por recurso, não por camada técnica. modules/orders/ é responsável pelos pedidos de ponta a ponta; evite pastas globais controllers/ e services/ que escondem a propriedade.
• Desenhe limites de módulo antes de desenhar caixas de microsserviços. Exports limpos de index.ts são mais baratos do que YAML do Kubernetes.
• Prefira extração "strangler" em vez de reescritas "big-bang". Mova uma capacidade para trás de um adaptador HTTP ou de eventos; mantenha as transações no monólito até que a propriedade dos dados esteja clara.
• Meça métricas DORA antes de dividir. Frequência de implantação, tempo de chumbo e taxa de falha de alterações indicam se a arquitetura é o gargalo.

B - Direção de Dependência

• Camadas de domínio e aplicação não importam Express, Fastify, decoradores Nest ou clientes ORM. O código do framework fica em infrastructure/.
• Importações entre módulos passam apenas pelo index.ts público. Proíba importações profundas em infrastructure/ de pares com ESLint ou dependency-cruiser em CI.
• Use portas para qualquer coisa que você irá simular em testes ou trocar em produção. Repositórios, gateways, relógios e geradores de ID são portas.
• Mantenha a raiz de composição fina. main.ts conecta adaptadores; não contém regras de negócios.
• Evite dependências circulares de módulos. Quebre ciclos com eventos ou invertendo dependências através de interfaces.

C - Dados e Consistência

• Atribua um módulo proprietário por tabela ou agregado. Outros módulos chamam APIs ou eventos, não modelos Prisma compartilhados.
• Documente explicitamente os limites de transação. Saiba quais casos de uso exigem ACID e quais toleram consistência eventual.
• Planeje consumidores outbox ou idempotentes antes de handoffs assíncronos. Entrega "pelo menos uma vez" é o padrão em workers Node distribuídos.
• Não compartilhe bancos de dados graváveis entre futuros serviços. Esquema por módulo dentro de um monólito ensaia a extração.
• Versionar payloads de eventos e API. Inclua campos schemaVersion; consumidores devem ignorar versões desconhecidas com segurança.

D - Operações e Observabilidade

• Envie traces OpenTelemetry antes do serviço #2. Você não pode depurar o que não pode ver através de chamadas HTTP.
• Logs estruturados com requestId em cada linha. pino ou equivalente; sem console.log não estruturado em caminhos de produção.
• Separe probes de liveness e readiness. Readiness verifica Postgres/Redis; liveness permanece leve para rollouts do kube.
• Implemente desligamento gracioso em SIGTERM. Esgote o servidor HTTP e feche os pools de DB antes de sair.
• Defina SLOs por jornada crítica do usuário. Checkout de pedidos p95 é mais importante do que a CPU média entre os pods.

E - Decisões e Governança

• Escreva ADRs para monólito vs serviços, escolha de framework e forks de armazenamento de dados. Inclua negativos e uma data de gatilho de revisão.
• Substitua ADRs em vez de excluí-los. Engenheiros futuros precisam do histórico de por que você reverteu o curso.
• Alinhe módulos à propriedade da equipe (Lei de Conway). Se dois squads possuem um módulo, espere erosão de limites.
• Execute revisões de arquitetura ao cruzar 10 engenheiros ou 3 squads em um repositório. Limites escorregam sem aplicação explícita.
• Rejeite slides que dizem "microsserviços para escala" sem RPS e dados da equipe. Evidência supera moda.

F - Adequação ao Runtime Node.js

• Perfilar o event loop antes do escalonamento horizontal. JSON síncrono em caminhos quentes não se conserta com mais pods.
• Descarregue trabalho intensivo em CPU para worker threads ou filas de jobs. Mantenha processos HTTP limitados por I/O.
• Fixe Node LTS em engines e CI. Node 24.18.0 Active LTS; teste atualizações em uma release dedicada.
• Padronize um framework HTTP por deployable. Express 5 ou Fastify 5 ou Nest 11 - não os três em um único processo.
• Tipifique limites com TypeScript 5.6+ modo estrito. Tipos DTO compartilhados são um vetor de acoplamento - versione-os intencionalmente.

FAQs

Relacionados

• Fundamentos de Arquitetura - exemplos introdutórios
• Monólito Modular - implementação de limites
• ADR: Monólito vs Serviços - modelo de decisão
• Checklist de Refatoração - auditoria pré-refatoração
• Microsserviços Quando Vale a Pena - quando dividir

Versões de 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.