Modularidade Node.js

Modularidade é a prática de dividir uma base de código Node.js de forma que cada parte tenha uma tarefa restrita e bem definida e dependa do mínimo possível do resto do sistema. É fácil confundir com "ter vários arquivos", mas a contagem de arquivos não diz nada sobre modularidade - um projeto com cinquenta arquivos pode ser tão emaranhado quanto um com cinco se cada arquivo importar livremente todos os outros.

Esta página é o modelo mental por trás do resto da seção: Noções Básicas de Modularidade mostra o padrão de aninhamento em código funcional, e Casos de Uso e Serviços, Padrão Repository e Padrões de Injeção de Dependência aprofundam em partes específicas dele. Aqui, o objetivo é entender o que realmente torna um backend Node.js modular: a direção em que suas dependências apontam, não quantas pastas ele tem.

Resumo

• Modularidade é controlar quais partes de um sistema podem depender de quais outras partes, de modo que as regras de negócio não dependam de mecanismos de entrega como frameworks HTTP ou bancos de dados.
• Por que Importa: Uma base de código onde a lógica de domínio importa Express diretamente não pode ser testada sem um servidor, não pode ser reutilizada de um CLI ou worker, e não pode trocar de framework sem tocar em todas as regras de negócio.
• Conceitos-Chave: acoplamento, coesão, direção de dependência, porta, adaptador, raiz de composição.
• Quando Usar: Estruturar um novo serviço desde o início, decidir onde uma peça de lógica pertence, revisar se uma alteração tocou em muitos arquivos não relacionados e planejar uma migração de framework ou banco de dados.
• Limitações / Trade-offs: Aninhamento estrito adiciona indireção - uma interface extra, um arquivo extra - que é cerimônia desperdiçada em um protótipo de cinco rotas e só se paga quando uma base de código tem lógica suficiente para proteger.
• Tópicos Relacionados: injeção de dependência, o padrão repository, arquitetura hexagonal, casos de uso e serviços de aplicação.

Fundamentos

Acoplamento é o quanto uma parte de um sistema conhece e depende de outra parte; coesão é o quão firmemente as responsabilidades dentro de uma parte pertencem juntas.

O objetivo da modularidade é baixo acoplamento entre as partes e alta coesão dentro de cada parte - peças que mudam pela mesma razão vivem juntas, e peças que mudam por razões diferentes não se arrastam mutuamente.

Um manipulador de rota e uma regra de cálculo de impostos mudam por razões completamente diferentes - um muda porque um formato de cabeçalho HTTP mudou, o outro porque a lei de uma jurisdição mudou - então agrupá-los em uma única função acopla duas fontes de mudança não relacionadas.

Uma analogia simples: um backend bem modularizado se comporta como um prédio com portas claramente rotuladas, onde o eletricista nunca precisa passar pela cozinha para chegar ao painel de disjuntores.

Os cômodos do prédio (módulos) cada um serve a um propósito, e os caminhos entre eles (dependências) são deliberados, não atalhos cortados através de paredes de suporte porque era conveniente naquele dia.

Especificamente em um backend Node.js, a parede de suporte mais comum que as pessoas cortam é o framework HTTP: importar tipos Request/Response ou chamar res.json() de dentro de uma peça de lógica de negócio vincula permanentemente essa lógica ao Express ou Fastify, mesmo que a regra de negócio em si não tenha nada a ver com HTTP.

Mecânicas e Interações

Modularidade na prática é uma disciplina de aninhamento: o código é agrupado em camadas, e as importações só são permitidas fluir em uma direção entre elas.

infraestrutura/http  ->  aplicação  ->  domínio
     (rotas)         (casos de uso)   (regras de negócio)
 
Permitido:   infraestrutura importa aplicação importa domínio
Proibido: domínio importa infraestrutura ou express

A camada de domínio contém regras de negócio e não tem nenhuma importação de framework - ela não sabe se está sendo chamada de uma rota HTTP, um worker de fila de mensagens ou um arquivo de teste. A camada de aplicação (frequentemente chamada de "casos de uso" ou "serviços") orquestra a lógica de domínio para cumprir uma operação específica, como "criar um pedido", pegando suas dependências como parâmetros simples em vez de buscar singletons globais. A camada de infraestrutura é onde os frameworks vivem - roteadores Express, clientes Prisma, clientes HTTP para APIs de terceiros - traduzindo entre os protocolos do mundo exterior e as chamadas de função simples da camada de aplicação.

Uma porta é a interface que a camada de aplicação define para algo que ela precisa, mas não quer saber a implementação concreta - mais comumente uma interface de repositório para persistência.

// domain/ports/order-repository.ts - uma promessa, não uma implementação
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

Um adaptador é a classe concreta na camada de infraestrutura que cumpre uma porta - um PostgresOrderRepository implementando OrderRepository, por exemplo. A camada de aplicação sempre importa a interface, nunca o adaptador, que é o que torna a troca de Postgres por DynamoDB uma mudança confinada a um novo arquivo adaptador em vez de uma reescrita de todos os casos de uso que tocam em pedidos.

A conexão de portas com adaptadores acontece em exatamente um lugar: a raiz de composição, tipicamente main.ts, que é o único arquivo em toda a base de código permitido a conhecer tanto um caso de uso quanto sua implementação concreta de Postgres ao mesmo tempo. Todos os outros arquivos dependem de interfaces; apenas a raiz de composição depende de classes.

Considerações Avançadas e Aplicações

O valor desse aninhamento é mais fácil de ver no que ele torna possível do que no que ele proíbe. Um caso de uso sem importações de framework pode ser testado unitariamente passando um repositório fake em memória, sem servidor vinculando uma porta e sem banco de dados rodando - testes que de outra forma precisariam de supertest e um banco de dados de teste rodam em milissegundos. O mesmo caso de uso também pode ser chamado de um worker de fila de mensagens, um job agendado ou um script CLI sem duplicar nenhuma lógica de negócio, porque "como a operação foi acionada" e "o que a operação faz" nunca foram acoplados em primeiro lugar.

Essa separação também determina o quão cara é uma migração de framework. Uma base de código onde a lógica de domínio nunca importou Express pode migrar para Fastify reescrevendo apenas a camada de infraestrutura; uma base de código onde as regras de negócio estão repletas de chamadas req/res tem que reescrever as próprias regras de negócio, o que é uma migração fundamentalmente mais arriscada e lenta porque a correção e a sintaxe do framework agora estão entrelaçadas.

À medida que uma base de código cresce além de algumas rotas, a próxima pergunta natural é como agrupar casos de uso, portas e adaptadores relacionados - apenas por camada técnica, ou por módulo de recurso (pedidos, faturamento, usuários) que cada um contém seu próprio aninhamento fino internamente. A maioria dos serviços Node.js de produção converge para o último: uma pasta shared/ para preocupações genuinamente transversais (classes base de erro, uma instância de logger) e pastas de recursos que possuem suas próprias regras de negócio, de modo que dois módulos nunca briguem sobre onde uma regra como cálculo de impostos pertence.

A aplicação importa tanto quanto o padrão em si - uma regra de aninhamento que existe apenas em uma página wiki se erode em algumas pull requests. Equipes que mantêm essa disciplina ao longo do tempo geralmente a codificam como uma regra ESLint (no-restricted-imports bloqueando express dentro de domain/) para que uma violação falhe na CI em vez de na memória da revisão de código.

Concepções Equivocadas Comuns

• "Modularidade significa apenas dividir o código em mais arquivos." A contagem de arquivos é ortogonal à modularidade - a propriedade que importa é quais arquivos podem importar quais outros arquivos, não quantos arquivos existem.
• "Interfaces (portas) são sobrecarga desnecessária se eu só usar um banco de dados." O valor não é a troca hipotética de banco de dados, é a testabilidade - uma porta permite que um caso de uso seja testado com um fake em memória, com ou sem nunca mudar de banco de dados.
• "Injeção de dependência requer um framework ou container." Passar dependências como parâmetros de função ou construtor simples é injeção de dependência; um container como Awilix ou o sistema de DI do NestJS é uma implementação da ideia, não um pré-requisito para ela.
• "Aninhamento atrasa todos os projetos, então não vale a pena no início." É um custo real em um protótipo de cinco rotas e uma economia real em um serviço com anos de regras de negócio pela frente - o trade-off depende da vida útil esperada e da densidade da lógica, não de uma regra universal.
• "Uma pasta shared/ é onde tudo o que é reutilizável pertence." Reutilizável e transversal não são a mesma coisa - a lógica de negócio que dois módulos de recurso precisam em conjunto deve ser de propriedade de um deles e exposta como um serviço, não jogada em um arquivo de utilitários compartilhado.

FAQs

Relacionados

• Noções Básicas de Modularidade - exemplos práticos do padrão de aninhamento descrito aqui
• Casos de Uso e Serviços - a camada de aplicação em profundidade
• Padrão Repository - o emparelhamento porta/adaptador mais comum
• Padrões de Injeção de Dependência - conexão manual vs. Awilix vs. DI do NestJS
• Arquitetura Hexagonal em Node - portas e adaptadores no nível da arquitetura
• Melhores Práticas de Modularidade - regras operacionais que decorrem deste modelo

Versões de Stack: Esta página é conceitual e não está vinculada a uma versão específica de stack.