Arquitetura em camadas no Node.js: como organizar 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 select e insert, 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 rigorosa de dados: prevenindo falhas de segurança e dados inconsistentes com Zod e TypeScript.
• Erros tratados num lugar só, com respostas consistentes: Tratamento global de erros no Node.js: respostas consistentes e logs úteis.
• Tipos compartilhados com o front e o app: TypeScript de ponta a ponta: reduzindo bugs em produção com tipagem unificada entre front, app e back.

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 do WOCOM Hub. Se o seu código virou um emaranhado, vamos conversar.