Boas Práticas da Filosofia Go

Dez princípios que mantêm as bases de código Go alinhadas com o ethos da linguagem: legível, explícito e operável em escala.

Como Usar Esta Lista

• Trate os itens como normas da equipe, não como detalhes de revisão pontuais - cite-os em guias de estilo e ADRs.
• Verifique novos pacotes e serviços contra as seções A–C antes de mesclar.
• Revise trimestralmente à medida que os lançamentos do Go adicionam idiomas (go fix modernizadores em 1.26 são um bom gatilho).
• Emparelhe com linters (golangci-lint, go vet) para que a filosofia se torne um sinal de CI, não de memória.

A - Simplicidade e Legibilidade

• Deixe gofmt cuidar da formatação. Sem debates de alinhamento personalizados em revisões; use gofmt/goimports em CI.
• Mantenha pacotes focados em uma única tarefa. Divida quando o godoc parecer uma gaveta de bagunça; prefira checkout em vez de util.
• Nomeie pelo propósito, não pelo padrão. UserStore é melhor que UserDAO; Go não é cosplay corporativo Java.
• Escreva godoc para cada símbolo exportado. Leitores futuros descobrem contratos através de pkg.go.dev e hovers de IDE.
• Prefira código claro a abstrações inteligentes. Se um engenheiro júnior não consegue rastrear o fluxo de controle em uma única passagem, simplifique.

B - APIs e Dependências

• Aceite interfaces, retorne structs. Interfaces permanecem pequenas nos sites dos consumidores; construtores retornam tipos concretos.
• Passe context.Context como o primeiro parâmetro em limites de I/O. Nunca armazene contexto em structs.
• Retorne (T, error) e envolva com %w. Documente erros sentinela com var ErrFoo = errors.New("...") para errors.Is estável.
• Injete dependências através de New em main. Evite var db *sql.DB global em bibliotecas; conecte explicitamente em cmd/.
• Minimize a área de superfície exportada. Desexporte helpers até que um segundo pacote realmente precise deles.

C - Concorrência e Operações

• Saiba como cada goroutine sai. Trabalhadores com tempo limite, respeite ctx.Done(), e evite fan-out ilimitado.
• Execute go test -race em CI em pacotes que usam goroutines. Filosofia sem detecção é pensamento positivo.
• Use a biblioteca padrão antes de importar frameworks. net/http, encoding/json e log/slog cobrem muitos serviços.
• Faça profiling antes de otimizar (pprof, tracer de execução). Medir se alinha com a cultura Go; adivinhar não.
• Envie binários estáticos com desligamento gracioso explícito. Manipule SIGTERM, descarregue manipuladores e alinhe com as semânticas de probe do Kubernetes.

D - Ferramentas e Evolução

• Mantenha-se atualizado sobre as versões suportadas do Go. Adquira ganhos de tempo de execução (GC padrão Green Tea em 1.26) e correções de segurança.
• Execute modernizadores go fix durante as atualizações. Deixe as ferramentas migrarem idiomas em vez de alterações manuais em monorepos.
• Fixe módulos e escaneie com govulncheck. Filosofia inclui higiene da cadeia de suprimentos, não apenas sintaxe.
• Trate a promessa de compatibilidade do Go 1 como um ativo da equipe. Evite quebrar APIs exportadas sem um plano de caminho de módulo /v2.

Aplicando Filosofia em Revisão de Código

• Bloqueio: concorrência propensa a race conditions, contexto ausente em manipuladores RPC/HTTP, interfaces exportadas que forçam mocks amplos.
• Discussão: divisões de pacotes, alterações na taxonomia de erros, novos frameworks de terceiros duplicando a biblioteca padrão.
• Adiamento: micro-otimizações sem perfis, renomeações por gosto estético quando o comportamento é estável.

FAQs

Relacionado

• Por que Go Existe - princípios por trás da lista de verificação
• Simplicidade como uma Restrição Deliberada no Design de API - detalhes no nível da API
• Fundamentos da Filosofia Go - exemplos executáveis de idiomas
• Quando Go é a Ferramenta Errada - quando não forçar o Go idiomático

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 da 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).