Boas Práticas para Funções, Métodos e Interfaces

Regras idiomáticas para projetar funções, métodos e interfaces que permanecem legíveis sob concorrência, testes e anos de atualizações de módulos.

Como Usar Esta Lista

• Aplique durante a revisão de API para novos pacotes e antes de estabilizar caminhos de módulo /v2.
• Verifique as fronteiras de manipulador/repositório em serviços HTTP e gRPC em relação às seções A–D.
• Emparelhe com golangci-lint (ireturn, revive, govet) para que as convenções se tornem um sinal de CI.
• Revise ao atualizar ferramentas Go - os modernizadores go fix em 1.26 podem mudar os idiomas.

A - Funções e Retornos

• Retorne (T, error) com error por último. Corresponde às expectativas do leitor e às convenções do staticcheck.
• Envolva erros com %w e prefixos de domínio. fmt.Errorf("checkout: charge: %w", err) preserva cadeias errors.Is.
• Evite retornos "nus" (naked returns), exceto para helpers curtos de defer/erro. Valores de return explícitos são escaneados mais rapidamente na revisão.
• Prefira opções funcionais em vez de listas de parâmetros crescentes. New(WithPort(8080)) escala sem quebrar os chamadores.
• Passe context.Context primeiro nas fronteiras de I/O. Nunca armazene contexto em structs; passe-o através de parâmetros.

B - Métodos e Receptores

• Escolha um estilo de receptor por tipo. Se algum método mutar, use receptores de ponteiro para todos os métodos desse tipo.
• Construtores retornam *T quando métodos de ponteiro existem. Garante a satisfação da interface sem surpresas de endereço.
• Mantenha receptores de valor para tipos imutáveis pequenos. IDs, tipos de dinheiro ou visualizações somente leitura onde a cópia é barata e segura.
• Não copie structs que contenham locks. sync.Mutex, sync.WaitGroup e campos semelhantes exigem apenas receptores de ponteiro.
• Nomeie construtores New ou New<Type>. Documente as dependências necessárias; valide as entradas antes de retornar.

C - Interfaces e Composição

• Defina interfaces nos consumidores com 1–3 métodos. Superfícies pequenas no estilo io superam interfaces Repository de nível empresarial.
• Aceite interfaces, retorne structs concretos. Parâmetros dependem do comportamento; New retorna *Service, não ServiceInterface.
• Evite exportar interfaces amplas dos produtores. Adicionar um método quebra todos os implementadores externos.
• Documente semânticas nil para retornos de interface. Prefira (*T, error) ou interfaces nil não tipadas - nunca ponteiros nil tipados em interfaces.
• Use tipos de função para hooks únicos. Middleware func(http.Handler) http.Handler permanece mais simples do que interfaces de um método quando nenhum mock é necessário.

D - Closures, Variádicos e Concorrência

• Copie variáveis de loop antes de closures de goroutine. id := id ou passe parâmetros para go func(id int){...}(id).
• Proteja valores de função nil antes da chamada. Callbacks opcionais devem ser no-op quando não definidos.
• Trate argumentos variádicos como verificações len==0, não identidade de slice nil. Chamadas com zero argumentos passam slices vazios não nil.
• Limite a captura de closure aos campos necessários. Evite reter objetos de requisição grandes em manipuladores de longa duração.
• Execute go test -race em pacotes que usam goroutines com estado capturado. A filosofia sem detecção falha em produção.

Aplicando a Lista na Revisão

• Bloqueio: nil tipado retornado como interface, estilos de receptor mistos quebrando interfaces, contexto ausente em I/O RPC/HTTP, bugs de captura de loop de goroutine.
• Discutir: divisão de interfaces, conversão de hooks de função para interfaces para testes, adição de opções variádicas vs. struct de configuração.
• Adiar: renomear funções por estética quando as assinaturas são estáveis e exportadas.

FAQs

Relacionados

• Funções e Interfaces: Modelo de Composição do Go - base conceitual para a seção C
• Definindo e Implementando Interfaces - padrões de interface do lado do consumidor
• Interface Nil vs Ponteiro Nil - evite retornos de interface nil tipados
• Métodos: Receptores de Valor vs Ponteiro - detalhes de consistência do receptor
• Literais de Função e Closures - captura segura e padrões de middleware

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 (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (conjunto de linters mais recente - verifique na compilação). pbqrthvqrf.vb|ptvb424|202607