Boas Práticas de Genéricos

Nomenclatura, design de constraints e adoção gradual em bases de código.

Estas regras mantêm o código genérico legível em revisões, estável para os chamadores e alinhado com os padrões da biblioteca padrão.

Como Usar Esta Lista

• Marque os itens durante a revisão de PR quando uma diff introduzir parâmetros de tipo.
• Comece novos pacotes com a seção A antes de exportar símbolos genéricos.
• Use a seção D ao atualizar toolchains Go ou habilitar golangci-lint em módulos genéricos.
• Revise trimestralmente à medida que a familiaridade da equipe aumenta - afrouxe apenas com benchmarks e ADRs.

A - Constraints e Nomenclatura

• Nomeie constraints quando reutilizadas ou exportadas. type NodeID interface { ~int64 } é melhor do que repetir listas de uniões.
• Prefira cmp.Ordered e comparable em vez de uniões copiadas. Mantenha o alinhamento com a semântica da biblioteca padrão.
• Use ~T quando tipos nomeados devem corresponder. Wrappers no estilo Celsius/Fahrenheit pertencem ao conjunto de tipos.
• Mantenha listas de uniões curtas (aproximadamente três membros) ou divida funções. Uniões amplas falham nas verificações de compilação e revisões.
• Use letras maiúsculas únicas (T, K, V) ou nomes de domínio (ID, E) para parâmetros de tipo. Evite abreviações fofas de várias letras em APIs públicas.

B - Superfície da API e exports

• Por padrão, use tipos concretos ou interfaces para APIs exportadas. Mantenha genéricos como helpers não exportados, a menos que os chamadores precisem de parametrização.
• Não exporte nomes de funções com muitos colchetes sem exemplos de documentação. Cada genérico exportado precisa de uma amostra de instanciação de uma linha.
• Evite métodos genéricos em tipos não genéricos. Apenas tipos genéricos carregam parâmetros para métodos em Go.
• Estabilize constraints antes da v1. Alterar uma constraint é uma mudança de tempo de compilação que quebra para genéricos downstream.
• Espelhe a divisão da biblioteca padrão: algoritmos genéricos em internal/, manipuladores simples fora. Corresponde ao layout de serviço chi / gin / echo.

C - Algoritmos e estruturas de dados

• Utilize slices, maps e cmp antes de cópias personalizadas. Mantenha menos, ganhe atualizações em tempo de execução.
• Documente cópia rasa vs. profunda em helpers de mapa. maps.Clone referencia valores de ponteiro.
• Use buffers circulares ou filas com capacidade limitada para FIFOs de longa duração. Evite vazamentos de memória de dequeue de slice.
• Exija comparable para conjuntos e deduplicação baseados em mapa. Não finja chaves de slice.
• Teste em tabela múltiplas instanciações (int, string, struct). Uma função de teste por comportamento, vários argumentos de tipo.

D - Desempenho, ferramentas e rollout

• Faça benchmark de interface vs. genérico antes de reescrever caminhos críticos. Registre os resultados no PR ou ADR.
• Observe o tamanho do binário em alvos WASM/TinyGo ao adicionar instanciações. Compile esses artefatos no CI se você os distribuir.
• Execute go test -race em contêineres genéricos usados a partir de goroutines. Regras de mutex inalteradas.
• Habilite golangci-lint em módulos que usam genéricos. Capture parâmetros redundantes e instanciações não utilizadas precocemente.
• Adote gradualmente: helpers internos primeiro, exporte após a segunda reutilização. Evite frameworks genéricos preemptivos.

E - Documentação e revisão

• Link para a justificativa da constraint no godoc. "K deve ser comparável porque esta função constrói map[K]int."
• Chame a atenção quando não usar a API genérica. Aponte para a alternativa baseada em interface.
• Prefira exemplos em testes Example* em vez de longas descrições em comentários. O compilador verifica os exemplos.
• Marque APIs genéricas no CHANGELOG como experimentais até que as constraints se estabilizem.
• Faça o onboarding com Fundamentos de Genéricos antes das páginas avançadas de constraints.

FAQs

Relacionados

• Quando Evitar Genéricos em APIs Go - guardrails de referência rápida
• Genéricos em Go: Constraints Sem Templates - visão geral da seção
• Parâmetros de Tipo e Interfaces de Constraint - profundidade da sintaxe
• Implicações de Desempenho dos Genéricos - orientação de benchmark
• Algoritmos Genéricos: Pacotes slices, maps & cmp - regra da biblioteca padrão primeiro

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - 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).

NzA2MjAyfDQ0NG9pZ2N8b2kuc2VkaXVnZWRvYw==