Checklist de Refatoração e Auditoria de Arquitetura

Sinais de alerta em acoplamento de pacotes, globais e abuso de init().

Percorra este checklist antes de um lançamento importante, após picos de onboarding ou quando os tempos de compilação e as taxas de incidentes aumentam juntos.

Como Usar Este Checklist

• Pontue cada nível durante uma revisão de arquitetura de uma hora ou uma retrospetiva sem culpa pós-incidente.
• Corrija itens Críticos antes de adicionar funcionalidades sobre a dívida técnica.
• Rastreie descobertas em tickets vinculados a ADRs quando a correção alterar limites.
• Reexecute trimestralmente ou quando o número de módulos ou o tamanho da equipe dobrar.

Crítico - Pare o Sangramento

1. Estado mutável global para banco de dados, configuração ou clientes: Substitua por injeção de construtor a partir de main.

   • Globais: var db *sql.DB usado entre pacotes
   • Injeção: NewService(repo Repository) configurado uma vez na inicialização

2. Ciclos de importação entre pacotes de produção: Extraia contratos compartilhados ou inverta a direção da dependência.

   • Ciclo: handler importa service importa handler
   • Correção: Mova interfaces para o consumidor ou para internal/contracts

3. init() executa I/O ou entra em pânico por má configuração: Falhe em main com erros claros em vez disso.

   • Efeito colateral de init: Abre o banco de dados em init()
   • Falha rápida em main: cfg, err := Load(); if err != nil { log.Fatal(err) }

4. Regras de negócios apenas em handlers HTTP: Mova validação e fluxos de trabalho para serviços com testes unitários.

   • Handler gordo: ServeHTTP de 200 linhas com SQL
   • Serviço: Register(ctx, email) testado sem httptest

5. Segredos ou endpoints codificados em pacotes de biblioteca: Carregue de env/flags apenas na raiz de composição.

   • Codificado: const apiURL = "https://prod..."
   • Struct de configuração: Config.APIURL validado na inicialização

Alto - Acoplamento e Limites

6. Pacote "Deus" (util, common, helpers): Divida por capacidade (internal/timeutil, internal/validate).
7. Pacotes de domínio importam net/http, gin ou código gerado por gRPC: Mova adaptadores para internal/adapter/*.
8. Interfaces amplas (10+ métodos) consumidas por um único chamador: Divida ou defina portas de um método do lado do consumidor.
9. Identificadores exportados que nenhum módulo externo usa: Desexporte ou mova para internal/ para congelar a superfície da API.
10. Binários cmd/ duplicando configuração de forma divergente: Extraia helpers Provide* compartilhados ou conjunto Wire.
11. Repositórios retornam DTOs HTTP ou modelos ORM com tags de framework: Mapeie para structs de domínio na fronteira do repositório.
12. Falta context.Context em funções de I/O: Adicione ctx como primeiro parâmetro; canalize a partir dos handlers.

Médio - Sinais de Manutenibilidade

13. Suite de testes requer Docker para testes de lógica de negócios pura: Introduza fakes nas fronteiras do serviço.
14. Strings de erro duplicadas em vez de sentinelas: Use var ErrNotFound = errors.New(...) e errors.Is.
15. Panics para erros esperados em bibliotecas: Retorne erros; reserve panic para bugs de programador.
16. Importações em branco (_) sem comentário explicando o efeito colateral: Documente o propósito de registro ou remova.
17. Pacotes nomeados apenas por camadas (models, controllers) com importações cruzadas: Reorganize por fatia de funcionalidade.
18. Mais de três níveis de pacotes aninhados sem propriedade: Achate ou alinhe com os limites da equipe.
19. Diretivas replace commitadas para caminhos de laptop locais: Use go.work localmente; mantenha go.mod portátil.
20. Falta de ADR para a última alteração importante de limite (divisão, adoção de ORM, RPC): Escreva ADR antes que a próxima alteração se acumule.

Baixo - Polimento e Custo Futuro

21. Logging inconsistente (fmt, log, slog misturados): Padronize em slog ou logger da equipe nas bordas.
22. Handlers sem limites de tamanho de requisição ou timeouts: Adicione timeouts http.Server e MaxBytesReader.
23. Módulo público sem LICENSE e releases marcadas: Adicione LICENSE; marque semver para consumidores.
24. Código gerado editado manualmente: Regere de go generate, sqlc ou buf em CI.
25. Comentários descrevem arquitetura obsoleta ("temporário até v2") anos depois: Atualize a documentação ou conclua a migração.

Aplicando o Checklist em Ordem

• Crítico (1-5): Resolva antes de escalar tráfego ou equipe - incidentes e risco de corrupção de dados dominam.
• Alto (6-12): Agende para o trimestre atual - cada item atrasa cada funcionalidade subsequente.
• Médio (13-20): Agrupe em refatorações adjacentes ao trabalho de funcionalidade - regra do escoteiro por pacote.
• Baixo (21-25): Vincule a sprints de tarefas de plataforma - reduz a fricção de onboarding.

FAQs

Relacionados

• Arquitetura em Go: Interfaces Pequenas, Dependências Explícitas - Arquitetura alvo
• Camadas Handler-Service-Repository - Destino da refatoração de camadas
• Registros de Decisão de Arquitetura para Equipes Go - Registrar resultados
• Padrões Anti-Padrões Comuns em Codebases Go - Cheiros de código
• Melhores Práticas de Arquitetura e Design - Hábitos de prevenção

Links Relacionados Externos

• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Learn Go with Tests - Introdução ao Go focada em TDD.
• Stack Overflow – Tag Go - Perguntas e respostas para programação Go.
• The Go Programming Language (ebook) - Donovan & Kernighan.
• Learning Go (2nd Edition, O'Reilly) - Jon Bodner na O'Reilly.

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).