Checklist de Regras do Go Eficaz
Vinte e cinco regras destiladas do Go Eficaz e da prática da comunidade.
//
Busque em todas as páginas da documentação
Vinte e cinco regras destiladas do Go Eficaz e da prática da comunidade.
Percorra esta lista ao fazer onboarding, auditar um pacote ou transformar comentários de revisão repetidos em política de equipe.
gofmt em cada commit: Código não formatado nunca faz merge; gofmt -w é a única ferramenta de estilo.
test -z "$(gofmt -l .)" em CIgoimports para higiene de imports: Imports ausentes e não utilizados falham na revisão, assim como bugs de lógica.
Verificar cada retorno de erro: Sem _ silencioso em erros, exceto em casos deliberados e documentados.
if err != nil em cada chamada falívelEnvolver com contexto usando %w: Chamadores precisam de errors.Is/errors.As através da pilha.
fmt.Errorf("failed") sem wrap ao inspecionar sentinelasTratar erros uma vez: Registrar ou retornar ou traduzir para status HTTP/gRPC - não os três.
Usar nomes curtos em escopos pequenos: i, err, ctx são aceitáveis em loops; nomes exportados permanecem descritivos.
Preferir := dentro de funções: Use var para valores zero em nível de pacote e clareza intencional de tipo.
Executar go vet em cada PR: vet visa bugs prováveis, não preferências.
go vet ./... verde em CIExportar apenas superfícies estáveis: Identificadores em maiúsculas são promessas de compatibilidade sob semver.
Godoc para cada símbolo exportado: Comentários começam com o nome do símbolo e descrevem o comportamento.
go doc / pkg.go.dev renderiza documentação completa do pacoteAceitar interfaces, retornar structs: Parâmetros permanecem flexíveis; retornos permanecem concretos, a menos que o wrapping seja explícito.
func Load(r io.Reader) (*Config, error)Definir interfaces nos consumidores: Produtores retornam tipos concretos; chamadores declaram interfaces mínimas.
type Reader interface { Read... } no pacote produtor "para extensibilidade"Preferir composição sobre embedding para comportamento: Use embedding para encaminhamento; não simule hierarquias de herança.
Tornar valores zero úteis quando possível: Chamadores não devem precisar sempre de construtores para tipos simples.
Usar receptores de ponteiro ao mutar: Receptores de valor para tipos imutáveis pequenos; mantenha a consistência por tipo.
Testes orientados por tabela com subtestes: Codificar casos como dados; nomear linhas com t.Run.
Exemplos em example_test.go para bibliotecas: Documentos executáveis aparecem em pkg.go.dev.
cmd/ internoInicializar mapas antes de escrever: make(map[K]V) ou literais; nunca atribua a mapas nil.
panic: assignment to entry in nil mapAtribuir resultados de append: s = append(s, x) porque a capacidade pode realocar.
make([]T, 0, n) quando o tamanho é conhecidoCopiar variáveis de loop ao iniciar goroutines: Capturar variáveis de loop explicitamente em closures quando necessário (padrões mais antigos) ou confiar na semântica do Go 1.22+ e ainda testar com -race.
go test -racePassar context como primeiro parâmetro: Nomeá-lo ctx; propagar para IO e RPC.
context.Context em structsNão usar panic para fluxo de controle: Panics são para bugs de programador e falha de init, não para erros esperados.
Manter pacotes main enxutos: main conecta dependências; a lógica vive em bibliotecas.
cmd/ + pacotes reutilizáveisUsar internal/ para pacotes não públicos: Limites impostos pelo compilador superam apenas comentários.
internal/Marcar módulos com semver intencional: Mudanças de API que quebram o código aumentam a versão principal em v1+ via novo caminho de módulo ou diretório de versão principal.
go mod tidy limpo em CICobertura suficiente para onboarding sem duplicar checklists especializados de segurança e desempenho.
Promova falhas repetidas em ADRs de equipe.
Formatação, algumas verificações de erro (errcheck), estilo de receptor (revive) e comentários de exportação.
O design de interface e os limites de pacotes permanecem para revisão humana.
A maioria das regras de Nível 1-2 se aplica.
Concorrência e subconjuntos da biblioteca padrão diferem; escopo de checklists por tag de build.
Cada item mapeia para uma seção do Go Eficaz mais os padrões operacionais da comunidade.
Leia a página explicativa primeiro para contexto de camadas.
Documente a exceção com benchmarks no PR.
As regras assumem clareza primeiro; caminhos críticos podem justificar desvios.
Automatize o Nível 1.
Use os Níveis 2-3 como cartões de revisão durante o primeiro mês.
No onboarding, auditorias trimestrais e após atualizações menores do Go que adicionam verificações vet.
Sim - adicione ao seu conjunto de ADRs.
Mantenha esta página alinhada com os idiomas portáteis do Go, não com escolhas apenas da organização.
Use apenas para registro de efeitos colaterais (drivers database/sql, formatos image).
Documente o motivo em um comentário; evite imports em branco por conveniência.
Não diretamente.
Divida quando os testes não puderem cobrir branches ou os revisores não puderem seguir o fluxo de controle.
Prefira parâmetros de tipo restritos em vez de interface{} quando a capacidade for conhecida.
Pequenas interfaces permanecem válidas nas fronteiras de integração.
Execute os exemplos Noções Básicas de Qualidade de Código localmente, depois habilite os mesmos alvos em CI.
Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verificar patch na compilação), chi (última versão - verificar na compilação), gin (última versão - verificar na compilação), echo (última versão - verificar na compilação), google.golang.org/grpc (última versão - verificar na compilação), sigs.k8s.io/controller-runtime (última versão - verificar na compilação), kubebuilder (última versão - verificar na compilação), tinygo (última versão - verificar alvos de placa na compilação), wazero (última versão - verificar na compilação) e golangci-lint (última versão - verificar conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026