‹M02·09Problemas reais de backend
0102030405060708091011

CAPÍTULO 09

Problemas reais de backend

Acoplamento e manutenibilidade — como identificar código que apodrece e como mantê-lo vivo por anos.

Por Thiago Souza7 min de leituraAtualizado em 2026-05

Acoplamento

Analogia da meia que prendeu no zíper: acoplamento é quando você puxa uma coisa e vem outra junto sem você querer. Ninguém quer sair de casa com a meia presa no zíper da calça.

Sintomas de código acoplado:

  • Mudei o nome de uma coluna no banco e quebrou o handler HTTP.
  • Para subir um teste eu preciso de Postgres, Redis, Kafka, RabbitMQ, mais o Wi-Fi do escritório.
  • Trocar JSON por Protobuf no contrato externo me obriga a mexer na regra de negócio.
  • O service importa o pacote pgx. (Vermelho gritante.)

Como reduzir:

  • Interfaces nas fronteiras (entre service e repo, entre service e cache, entre service e API externa).
  • DTOs separados das entidades — o JSON da API não precisa ser idêntico à struct salva no banco.
  • Erros de domínio — o service devolve task.ErrNotFound, não pgx.ErrNoRows.
  • Injeção de dependência via construtor — peças recebem suas dependências de fora; não criam db, _ := sql.Open(...) no meio do código.

Manutenibilidade

Analogia da casa de 50 anos: dois imóveis com a mesma idade. Um tem manutenção em dia: pintura nova, encanamento revisto, papelada organizada. O outro está caindo aos pedaços porque o dono "deixou pra depois". Os dois começaram iguais. A diferença é o cuidado contínuo.

O que faz código ser manutenível:

  • Pacotes pequenos com responsabilidade clara. Se você não consegue resumir o pacote em uma frase, ele faz coisas demais.
  • Nomes que dizem o que fazem. ProcessData é horrível. RecalculateInvoiceTotal é ótimo.
  • Testes que rodam rápido e localmente. Se o teste só roda em CI, ninguém escreve teste novo.
  • Documentação onde dói. Não documente o óbvio. Documente o "por que" (decisão de design, trade-off).
  • Boundaries claras. Toda vez que um time mexe no código de outro, tem fricção. Boundaries reduzem fricção.
  • Configuração externa — os.Getenv, viper, kelseyhightower/envconfig. Nunca hardcode.
  • Refatoração contínua. Encontrou código ruim numa área que você está mexendo? Melhora um pouquinho. "Regra do escoteiro": deixe o acampamento mais limpo do que você encontrou.

Sintomas de código que está apodrecendo:

  • Um pacote com 4000 linhas e 30 dependências.
  • Função com 12 parâmetros.
  • Nomes genéricos: Manager, Processor, Helper, Util.
  • "Não mexe nesse arquivo, ninguém entende mais."
  • Bug em produção e ninguém sabe quem é dono daquela parte.