Arquitetura em camadas no Node.js: Controllers e Services
Rotas com 400 linhas, regra de negócio misturada com SQL e medo de mexer em qualquer coisa? Veja como organizar um backend Node.js em Controllers, Services e Repositories.
Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura
Rotas com 400 linhas, regra de negócio misturada com SQL e medo de mexer em qualquer coisa? Veja como organizar um backend Node.js em Controllers, Services e Repositories.
Todo backend começa simples: uma rota, uma consulta, uma resposta. Seis meses depois, o mesmo arquivo valida dados, aplica desconto, grava no banco, envia e-mail e formata a resposta. Ninguém quer mexer nele — e cada mudança quebra algo em outro lugar. A arquitetura em camadas existe para impedir isso.
As três camadas e o que cada uma pode fazer
- Controller: recebe a requisição HTTP, valida a entrada e devolve a resposta. Não conhece banco de dados.
- Service: a regra de negócio. "Pedido acima de R$ 500 tem frete grátis" mora aqui. Não conhece HTTP.
- Repository: fala com o banco. Sabe fazer
selecteinsert, não sabe o que é frete grátis.
// controller
export async function criarPedido(req: Request, res: Response) {
const dados = PedidoSchema.parse(req.body)
const pedido = await pedidoService.criar(dados, req.user.id)
res.status(201).json(pedido)
}
// service
export async function criar(dados: NovoPedido, clienteId: string) {
const frete = dados.total >= 500 ? 0 : await calcularFrete(dados.cep)
return pedidoRepository.inserir({ ...dados, frete, clienteId })
}Por que vale o esforço
- Testes: dá para testar a regra de negócio sem subir servidor nem banco.
- Troca de peças: mudar de banco ou expor a mesma regra numa fila não exige reescrever tudo.
- Onboarding: um dev novo sabe onde procurar cada coisa.
Os complementos que fecham o desenho
- Validação de entrada rigorosa na borda, com Zod: Validação de dados com Zod e TypeScript: guia prático.
- Erros tratados num lugar só, com respostas consistentes: Tratamento global de erros no Node.js: respostas e logs.
- Tipos compartilhados com o front e o app: TypeScript de ponta a ponta: menos bugs em produção.
Cuidado com o exagero
Camadas demais também atrapalham. Interfaces para tudo, cinco níveis de abstração e "factories" de factories tornam um CRUD simples uma maratona. O objetivo é clareza, não cerimônia — tema que discutimos em Microserviços ou monólito modular: o que sua empresa precisa de verdade.
É assim que estruturamos os sistemas web e o backend da 
- Node.js
- Arquitetura
- Backend
- TypeScript
Escrito por
Roger C. RibeiroFundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.
Serviços relacionados
Resolver de vez, com quem faz isso todo dia
Precisa de uma API ou integração que não caia quando o negócio crescer?
Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.
Continue lendo
Tudo sobre Backend & APIs- Ler artigo
Backend & APIs3 min
Validação de dados com Zod e TypeScript: guia prático
TypeScript não valida o que chega da internet. Veja como usar Zod para barrar dados inválidos na entrada da API e do formulário — com um único esquema.
- Ler artigo
Backend & APIs3 min
Tratamento global de erros no Node.js: respostas e logs
Cada rota trata erro de um jeito, o cliente recebe stack trace e ninguém acha o problema no log. Veja como centralizar o tratamento de erros no Node.js.
- Ler artigo
Backend & APIs3 min
Microserviços ou monólito modular: o que sua empresa precisa de verdade
Microserviços viraram sinônimo de arquitetura moderna — e de projetos caros e frágeis. Veja por que o monólito modular costuma ser a escolha certa.