Resumo de Regras e Melhores Práticas de Go

Índice transversal de regras que liga cada checklist do site.

Estas regras destilam a seção go-rules e apontam para checklists especializados em concorrência, módulos, segurança e desempenho.

Como Usar Esta Lista

• Novos contribuidores: comece com o Guia Rápido de Regras de Go, depois o Nível A aqui.
• Autores de bibliotecas: aplique os Níveis A + B antes de marcar v1.x.
• Equipes de serviços: adicione o Nível C antes do lançamento em produção.
• Link para esta página em modelos de CONTRIBUTING e PR como o índice de regras.

A - Idiomas Fundamentais

• Trate Effective Go como a linha de base narrativa. Checklists da comunidade os operacionalizam; não crie cópias desatualizadas.
• Automatize gofmt, goimports, vet e testes em CI. Regras objetivas nunca devem depender da memória do revisor.
• Verifique cada retorno de erro nos limites. Bibliotecas retornam; aplicações traduzem para logs e códigos de saída uma vez.
• Envolva erros com %w quando os chamadores inspecionarem sentinelas. Mensagens opacas quebram cadeias de errors.Is.
• Use nomes curtos em escopos pequenos e nomes exportados descritivos. O comprimento do escopo impulsiona a nomenclatura, conforme Effective Go.
• Documente cada símbolo exportado com godoc. APIs exportadas são contratos semver para bibliotecas.
• Percorra o Checklist de Regras do Effective Go durante o onboarding. Vinte e cinco itens cobrem idiomas diários.

B - API, módulos e dependências

• Coloque context.Context primeiro em funções de IO e RPC. Nomeie-o ctx; nunca armazene contexto em structs.
• Aceite interfaces, retorne tipos concretos. Consumidores definem interfaces pequenas; produtores retornam structs.
• Use internal/ para pacotes não públicos. A aplicação do compilador supera comentários "não importar".
• Execute go mod tidy em cada alteração de módulo. Confirme diffs de go.sum atomicamente com imports.
• Marque lançamentos de bibliotecas com semver. Mudanças que quebram exigem bumps maiores ou caminhos /v2.
• Mantenha dependências diretas mínimas e controladas. Execute go mod why -m em novas requisições.
• Aplique Regras de Design de API para Bibliotecas Go antes de ampliar exports.
• Aplique Regras de Módulo e Dependência em auditorias de plataforma.

C - Concorrência, segurança e desempenho

• Dê a cada goroutine um caminho de saída ligado ao contexto ou WaitGroup. Vazamentos se manifestam como travamentos no desligamento e OOM.
• Atribua um único proprietário para fechar cada canal. Recebedores nunca fecham; documente a propriedade nos tipos.
• Execute go test -race em pacotes que usam goroutines ou mapas compartilhados. Falhas de race bloqueiam o merge.
• Use o Checklist de Regras de Concorrência para pools de workers e manipuladores de streaming.
• Valide a entrada externa nos limites HTTP/gRPC. SQL parametrizado, limites de tamanho e templates seguros.
• Mantenha segredos fora do código-fonte, logs e erros voltados para o cliente. Carregue de segredos do orquestrador em tempo de execução.
• Execute govulncheck quando as dependências mudarem. Triagem de CVEs alcançáveis com upgrade ou aceitação datada.
• Aplique Regras de Segurança para Serviços Go antes dos portões de lançamento.
• Perfilar antes de PRs de otimização serem mesclados. Anexe evidências de CPU ou alocação a alegações de aceleração.
• Prefira código claro por padrão; otimize apenas caminhos comprovadamente quentes. Registre exceções com benchmarks.
• Siga Regras de Desempenho: Quando Otimizar para trabalho de SLO.

D - Cultura de revisão e padrões de vida

• Emparelhe regras com Padrões de Revisão de Código para Equipes Go. Lint é o piso; revisão é o teto.
• Promova um "nit" de revisão repetido para um linter ou ADR. Regras devem encolher a superfície de debate ao longo do tempo.
• Reaudite as regras após atualizações menores do Go. Novos verificadores e modernizadores go fix mudam a aplicação.
• Nivele explicitamente a rigidez de bibliotecas vs. serviços. Módulos publicados permanecem conservadores em exports.
• Link para modelos de PR neste índice. Autores se auto-verificam antes de solicitar revisão.

FAQs

Relacionado

• Effective Go como um Padrão Vivo - explicador da seção
• Guia Rápido de Regras de Go - introdução executável
• Checklist de Regras do Effective Go - vinte e cinco idiomas centrais
• Melhores Práticas de Linting e Qualidade de Código - aplicação de toolchain
• Erros como Valores: A Filosofia de Erros do Go - cultura de erros

Links Externos Relacionados

• Effective Go - Guia oficial para escrever Go claro e idiomático.
• Go Wiki – Learn - Recursos de aprendizado curados pela comunidade.
• Site Oficial do Go / Documentação - Hub principal de documentação.
• Learning Go (2ª Edição) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

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