Boas Práticas de Arquitetura e Design

Evoluindo bases de código Go sem reescritas "big-bang".

Estes hábitos mantêm serviços testáveis, módulos publicáveis e refatorações incrementais conforme os requisitos mudam.

Como Usar Esta Lista

• Adote durante a configuração greenfield e antes de cada versão principal ou divisão de serviço.
• Aplique com revisão de código, regras de golangci-lint depguard e reuniões de arquitetura.
• Use em conjunto com ADRs quando uma regra for controversa ou custosa a curto prazo.
• Revise quando o tamanho da equipe, escopo de conformidade ou ordem de magnitude do tráfego mudar.

A - Limites e dependências

• Mantenha a composição apenas em cmd/. main constrói tipos concretos; bibliotecas expõem funções New.
• Defina interfaces nos consumidores. Portas de um ou dois métodos são melhores que dumps de interfaces do lado do provedor.
• Use internal/ para implementação não pública. Deixe o compilador impor os limites do módulo.
• Proíba ciclos de importação em código de produção. Ciclos sinalizam um ponto de separação incorreto - extraia contratos ou inverta dependências.
• Passe context.Context pelos caminhos de requisição. O cancelamento pertence aos métodos de serviço e repositório.

B - Camadas e pacotes

• Handlers adaptam o transporte; serviços definem as regras. Sem chamadas SQL ou de SDK de fornecedor em handlers HTTP.
• Organize por funcionalidade quando as equipes se alinharem aos domínios. internal/billing é melhor que pastas apenas de camada que se importam mutuamente.
• Mapeie DTOs nas bordas. JSON, protobuf e linhas SQL param nos adaptadores - structs de domínio permanecem sem tags.
• Mantenha frameworks na periferia. Roteadores e ORMs não devem vazar para pacotes de domínio.
• Prefira errgroup para concorrência limitada. Vincule o tempo de vida da goroutine ao context da requisição.

C - Módulos, APIs e evolução

• Execute go mod tidy antes do merge. Gráficos limpos reduzem surpresas em atualizações no CI.
• Marque lançamentos de bibliotecas com semver. Quebras principais recebem caminhos de módulo /v2 e notas de migração.
• Escreva ADRs para movimentações de limites. Divisões, estilo de DI e escolhas de datastore precisam de um rastro em papel.
• Refatore em fatias verticais. Extraia uma funcionalidade de ponta a ponta antes de movimentos horizontais "big bang".
• Meça antes de dividir microsserviços. Desvio de CPU, acoplamento de lançamento ou conformidade impulsionam divisões - não estética.

D - Testes e portões de qualidade

• Teste unidades de serviços com fakes, não Docker. Reserve testes de integração para limites de adaptadores.
• Use erros sentinela e encapsulamento %w de forma consistente. Handlers mapeiam com errors.Is, não comparação de strings.
• Execute go test ./... e go vet ./... no CI. Adicione golangci-lint com depguard para globais e ciclos.
• Teste de contrato de esquemas RPC e de eventos. Verificações de quebra de buf ou testes orientados pelo consumidor evitam desvios.
• Faça benchmark de caminhos quentes antes de otimizar a arquitetura. Perfure antes de introduzir caches, shards ou serviços.

E - Operações e observabilidade

• Configure logging estruturado na inicialização. slog ou padrão da equipe com IDs de trace/requisição nas bordas.
• Exporte OpenTelemetry desde o primeiro dia. Traces entre handlers, DB e HTTP de saída simplificam incidentes.
• Defina timeouts do servidor HTTP e limites de corpo. Proteja contra slowloris e uploads excessivos.
• Envie binários estáticos do CI. Mesmo artefato do laptop para produção; sem go build no servidor.
• Documente o desligamento gracioso em main. Drene requisições em andamento em SIGTERM antes de sair.

FAQs

Relacionados

• Arquitetura em Go: Interfaces Pequenas, Dependências Explícitas - Fundamento conceitual
• Noções Básicas de Arquitetura Go - Exemplos iniciais executáveis
• Lista de Verificação de Refatoração e Auditoria de Arquitetura - Encontre dívidas para corrigir
• Registros de Decisão de Arquitetura para Equipes Go - Modelos de decisão
• Camadas Handler-Service-Repository - Padrão de camadas padrão

Links Externos Relacionados

• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Go Wiki – Learn - Recursos de aprendizado curados pela comunidade.
• Go Daily / Community News - Notícias diárias curadas, lançamentos e discussões sobre Go.
• Learning Go (2nd Edition) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - 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).