Buenas Prácticas para Funciones, Métodos e Interfaces

Reglas idiomáticas para diseñar funciones, métodos e interfaces que se mantengan legibles bajo concurrencia, pruebas y años de actualizaciones de módulos.

Cómo Usar Esta Lista

• Aplica durante la revisión de API para nuevos paquetes y antes de estabilizar las rutas de módulos /v2.
• Cruza los límites de manejadores/repositorios en servicios HTTP y gRPC con las secciones A–D.
• Empareja con golangci-lint (ireturn, revive, govet) para que las convenciones se conviertan en señal de CI.
• Revisa al actualizar las herramientas de Go - los modernizadores go fix en 1.26 pueden cambiar los modismos.

A - Funciones y Retornos

• Devuelve (T, error) con error al final. Coincide con las expectativas del lector y las convenciones de staticcheck.
• Envuelve errores con %w y prefijos de dominio. fmt.Errorf("checkout: charge: %w", err) preserva las cadenas de errors.Is.
• Evita retornos desnudos excepto para ayudantes cortos de defer/errores. Los return explícitos escanean más rápido en la revisión.
• Prefiere opciones funcionales sobre listas de parámetros crecientes. New(WithPort(8080)) escala sin romper a los llamadores.
• Pasa context.Context primero en los límites de I/O. Nunca almacenes el contexto en structs; pásalo a través de los parámetros.

B - Métodos y Receptores

• Elige un estilo de receptor por tipo. Si algún método muta, usa receptores de puntero para todos los métodos de ese tipo.
• Los constructores devuelven *T cuando existen métodos de puntero. Asegura la satisfacción de la interfaz sin sorpresas de dirección.
• Mantén receptores de valor para tipos inmutables pequeños. IDs, tipos de dinero o vistas de solo lectura donde la copia es barata y segura.
• No copies structs que contengan bloqueos. sync.Mutex, sync.WaitGroup y campos similares solo requieren receptores de puntero.
• Nombra los constructores New o New<Type>. Documenta las dependencias requeridas; valida las entradas antes de devolver.

C - Interfaces y Composición

• Define interfaces en los consumidores con 1–3 métodos. Superficies pequeñas al estilo io superan a las interfaces Repository de toda la empresa.
• Acepta interfaces, devuelve structs concretos. Los parámetros dependen del comportamiento; New devuelve *Service, no ServiceInterface.
• Evita exportar interfaces amplias de los productores. Añadir un método rompe a todos los implementadores externos.
• Documenta la semántica de nil para los retornos de interfaz. Prefiere (*T, error) o interfaces nil sin tipo - nunca punteros nil tipados en interfaces.
• Usa tipos de función para hooks individuales. El middleware func(http.Handler) http.Handler se mantiene más simple que las interfaces de un solo método cuando no se necesita un mock.

D - Clausuras, Variádicos y Concurrencia

• Copia las variables de bucle antes de las clausuras de goroutine. id := id o pasa parámetros a go func(id int){...}(id).
• Protege los valores de función nil antes de llamar. Las callbacks opcionales no hacen nada cuando no están configuradas.
• Trata los argumentos variádicos como comprobaciones de len==0, no como identidad de slice nil. Las llamadas de cero argumentos pasan slices vacíos no nil.
• Limita la captura de clausuras a los campos necesarios. Evita retener objetos de solicitud grandes en manejadores de larga duración.
• Ejecuta go test -race en paquetes que usan goroutines con estado capturado. La filosofía sin detección falla en producción.

Aplicando la Lista en la Revisión

• Bloqueante: nil tipado devuelto como interfaz, estilos de receptor mixtos que rompen interfaces, contexto faltante en I/O de RPC/HTTP, errores de captura de bucle de goroutine.
• Discutir: dividir interfaces, convertir hooks de función a interfaces para pruebas, añadir opciones variádicas frente a struct de configuración.
• Aplazar: renombrar funciones por estética cuando las firmas son estables y exportadas.

Preguntas Frecuentes

Relacionado

• Funciones e Interfaces: El Modelo de Composición de Go - base conceptual para la sección C
• Definición e Implementación de Interfaces - patrones de interfaz del lado del consumidor
• Interfaz Nil vs Puntero Nil - evita retornos de interfaz nil tipados
• Métodos: Receptores de Valor vs Puntero - detalles de consistencia del receptor
• Literales de Función y Clausuras - captura segura y patrones de middleware

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