Pular para o conteúdo

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 select e insert, não sabe o que é frete grátis.
ts
// 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

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 Ícone da StarpStarp. Se o seu código virou um emaranhado, vamos conversar.

  • Node.js
  • Arquitetura
  • Backend
  • TypeScript
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador 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.