Melhores Práticas da Toolchain Go

Builds reproduzíveis, integração de CI e fixação da toolchain.

Estas regras mantêm os fluxos de trabalho do comando go consistentes, desde laptops até CI e artefatos de release.

Como Usar Esta Lista

• Aplique durante a revisão de PR quando comandos de dependência, build ou teste mudarem.
• Espelhe os mesmos valores de GOPRIVATE, GOPROXY e GOTOOLCHAIN na CI e na documentação do desenvolvedor.
• Execute go mod tidy, go test ./... e linters em cada aumento de dependência antes do merge.
• Revise após atualizações menores do Go; modernizadores e analisadores vet expandem a cada release.

A - Higiene da Toolchain e de Módulos

• Fixe a versão do Go em go.mod e documente a política de GOTOOLCHAIN. Colegas de equipe e CI devem resolver o mesmo compilador; use auto apenas quando aceitar downloads automáticos.
• Execute go mod tidy após qualquer alteração de importação ou dependência. Mantém as linhas require mínimas e go.sum precisas.
• Commite go.sum sempre que go.mod mudar. Checksums são parte do contrato de build reproduzível.
• Defina GOPRIVATE para cada prefixo de módulo interno. Evita vazar caminhos privados para o proxy público e banco de dados de sum.
• Coloque um proxy interno (Athens/Artifactory) antes de proxy.golang.org. Acelera a CI e sobrevive a interrupções upstream.

B - Comandos de Build e Release

• Envie artefatos de go build, não go run, em produção. run recompila a cada invocação e oculta o caminho do binário.
• Use -trimpath e -ldflags="-s -w" para binários de release. Reduz o tamanho e remove caminhos de host de stacks.
• Nomeie saídas explicitamente com -o bin/<nome>. Evita colisões ao construir múltiplos comandos em uma única etapa de pipeline.
• Compile cruzado com CGO_ENABLED=0 a menos que você realmente precise de cgo. Matrizes Go puras são mais simples em um único builder Linux.
• Registre go version e go env nos logs de release. Acelera a depuração quando a CI e os builds do laptop divergem.

C - Portões de Teste, Vet e Lint

• Execute go test ./... (ou ./... com -race na CI) em cada PR. O portão padrão antes do merge.
• Execute go vet ./... antes de linters opcionais. Linha de base de configuração zero da stdlib.
• Execute golangci-lint (ou staticcheck) com uma configuração commitada. Regras de toda a equipe além do vet.
• Use go test -count=1 enquanto depura flakes; corrija a causa raiz antes do merge. Não confie no cache de teste desabilitado na CI de produção para sempre.
• Execute go fix -diff após atualizações do Go, então aplique com revisão. Modernizadores capturam idiomatismos que os dados de treinamento podem perder.

D - Cache, Vendor e CI Hermética

• Cache GOMODCACHE e GOCACHE na CI. Etapas de aquecimento de go mod download compensam em cada job.
• Use -mod=readonly na CI quando não estiver usando vendor. Falha builds que modificam go.mod silenciosamente.
• Re-vendorize no mesmo commit das alterações de dependência ao usar vendor/. Desvios quebram pipelines -mod=vendor.
• Evite go clean -modcache na CI rotineira. Limpe caches apenas quando a corrupção for comprovada.
• Verifique a autenticação de módulo privado na CI com um go mod download em modo seco. Capture a expiração do token antes das etapas de compilação.

E - Codegen e Tags

• Fixe as versões dos geradores em diretivas //go:generate. go run tool@version supera binários locais não documentados.
• Falhe a CI em desvios de go generate (git diff --exit-code). Saída gerada permanece sincronizada com as fontes.
• Documente os -tags necessários para builds de produção. O go test padrão pode pular arquivos com tags que a CI nunca exercita.
• Teste em matriz as combinações críticas de tags. Pelo menos os conjuntos de tags padrão e de produção.
• Mantenha tags de build para backends em tempo de compilação, não para toggles de recursos de ops. Configuração em tempo de execução evita churn de reconstrução.

FAQs

Relacionado

• O Comando go: Ciclo de Vida de Build, Teste e Módulos - visão geral conceitual
• Noções Básicas da Toolchain Go - exemplos de comandos
• go build, run, install & clean - flags de release
• go mod tidy, vendor, download & graph - fluxos de trabalho de dependência
• Compilação Cruzada e Proxies de Módulos Privados - configuração de env

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