Mejores Prácticas para Genéricos

Nomenclatura, diseño de restricciones y adopción gradual en bases de código.

Estas reglas mantienen el código genérico legible en las revisiones, estable para los llamadores y alineado con los patrones de la biblioteca estándar.

Cómo Usar Esta Lista

• Marca los elementos durante la revisión de PR cuando una diferencia introduce parámetros de tipo.
• Comienza nuevos paquetes con la sección A antes de exportar símbolos genéricos.
• Usa la sección D al actualizar las cadenas de herramientas de Go o al habilitar golangci-lint en módulos genéricos.
• Revisa trimestralmente a medida que crece la familiaridad del equipo: relaja solo con benchmarks y ADRs.

A - Restricciones y nomenclatura

• Nombrar restricciones cuando se reutilizan o exportan. type NodeID interface { ~int64 } es mejor que repetir listas de uniones.
• Preferir cmp.Ordered y comparable sobre uniones copiadas. Mantente alineado con la semántica de la biblioteca estándar.
• Usar ~T cuando los tipos nombrados deban coincidir. Los envoltorios estilo Celsius/Fahrenheit pertenecen al conjunto de tipos.
• Mantener las listas de uniones cortas (aproximadamente tres miembros) o dividir funciones. Las uniones amplias fallan las comprobaciones de compilación y las revisiones.
• Escribir parámetros de tipo como letras mayúsculas únicas (T, K, V) o nombres de dominio (ID, E). Evita abreviaturas lindas de varias letras en APIs públicas.

B - Superficie de API y exportaciones

• Por defecto, las APIs exportadas deben ser tipos concretos o interfaces. Mantén los genéricos como ayudantes no exportados a menos que los llamadores necesiten parametrización.
• No exportar nombres de funciones con muchos corchetes sin ejemplos de documentación. Cada genérico exportado necesita una muestra de instanciación de una línea.
• Evitar métodos genéricos en tipos no genéricos. Solo los tipos genéricos llevan parámetros a los métodos en Go.
• Estabilizar las restricciones antes de la v1. Cambiar una restricción es un cambio de tiempo de compilación que rompe la compatibilidad para genéricos posteriores.
• Reflejar la división de la biblioteca estándar: algoritmos genéricos en internal/, manejadores simples fuera. Coincide con el diseño de servicio de chi / gin / echo.

C - Algoritmos y estructuras de datos

• Usar slices, maps y cmp antes que copias personalizadas. Mantén menos código, obtén actualizaciones en tiempo de ejecución.
• Documentar la copia superficial vs. profunda en ayudantes de mapas. maps.Clone alias los valores de puntero.
• Usar búferes circulares o colas con capacidad limitada para FIFOs de larga duración. Prevenir fugas de memoria en la eliminación de slices.
• Requerir comparable para conjuntos y deduplicación basados en claves de mapa. No simular claves de slice.
• Probar en tabla múltiples instanciaciones (int, string, struct). Una función de prueba por comportamiento, varios argumentos de tipo.

D - Rendimiento, herramientas y despliegue

• Comparar en benchmarks la interfaz frente a genéricos antes de reescribir rutas críticas. Registrar resultados en PR o ADR.
• Vigilar el tamaño del binario en objetivos WASM/TinyGo al agregar instanciaciones. Compilar estos artefactos en CI si los distribuyes.
• Ejecutar go test -race en contenedores genéricos utilizados desde goroutines. Las reglas de mutex no cambian.
• Habilitar golangci-lint en módulos que usan genéricos. Detectar parámetros redundantes e instanciaciones no utilizadas tempranamente.
• Adoptar gradualmente: primero ayudantes internos, exportar después de la segunda reutilización. Evitar marcos genéricos preventivos.

E - Documentación y revisión

• Enlazar la justificación de la restricción en godoc. "K debe ser comparable porque esta función construye map[K]int."
• Indicar cuándo no usar la API genérica. Señalar la alternativa basada en interfaces primero.
• Preferir ejemplos en pruebas Example* sobre prosa de comentarios largos. El compilador verifica los ejemplos.
• Marcar las APIs genéricas en CHANGELOG como experimentales hasta que las restricciones se estabilicen.
• Onboarding con Conceptos Básicos de Genéricos antes de las páginas avanzadas de restricciones.

Preguntas Frecuentes

Relacionado

• Cuándo Evitar Genéricos en APIs de Go - guardarraíles de referencia rápida
• Genéricos en Go: Restricciones sin Plantillas - resumen de la sección
• Parámetros de Tipo e Interfaces de Restricción - profundidad de sintaxis
• Implicaciones de Rendimiento de los Genéricos - guía de benchmarks
• Algoritmos Genéricos: Paquetes slices, maps y cmp - regla de la biblioteca estándar primero

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).

NzA2MjAyfDQ0NG9pZ2N8b2kuc2VkaXVnZWRvYw==