Resumen de Reglas y Mejores Prácticas de Go

Índice transversal de reglas que enlaza cada lista de verificación del sitio.

Estas reglas destilan la sección de reglas de Go y apuntan a listas de verificación especializadas para concurrencia, módulos, seguridad y rendimiento.

Cómo Usar Esta Lista

• Nuevos contribuyentes: comience con Go Rules Quickstart, luego el Nivel A aquí.
• Autores de bibliotecas: aplique los Niveles A + B antes de etiquetar v1.x.
• Equipos de servicios: agregue el Nivel C antes del lanzamiento en producción.
• Enlace a esta página desde las plantillas de CONTRIBUTING y PR como el índice de reglas.

A - Idiomas Fundamentales

• Trate Effective Go como la base narrativa. Las listas de verificación de la comunidad las operacionalizan; no cree copias desactualizadas.
• Automatice gofmt, goimports, vet y las pruebas en CI. Las reglas objetivas nunca deben depender de la memoria del revisor.
• Verifique cada retorno de error en los límites. Las bibliotecas devuelven; las aplicaciones traducen a registros y códigos de salida una vez.
• Envuelva los errores con %w cuando los llamadores inspeccionen centinelas. Los mensajes opacos rompen las cadenas de errors.Is.
• Use nombres cortos en ámbitos pequeños y nombres exportados descriptivos. La longitud del ámbito impulsa la nomenclatura, según Effective Go.
• Documente cada símbolo exportado con godoc. Las API exportadas son contratos semver para bibliotecas.
• Recorra la Effective Go Rules Checklist durante la incorporación. Veinticinco elementos cubren los modismos diarios.

B - API, módulos y dependencias

• Ponga context.Context primero en funciones de IO y RPC. Nómbrelo ctx; nunca almacene contexto en structs.
• Acepte interfaces, devuelva tipos concretos. Los consumidores definen interfaces pequeñas; los productores devuelven structs.
• Use internal/ para paquetes no públicos. La aplicación del compilador supera los comentarios de "no importar".
• Ejecute go mod tidy en cada cambio de módulo. Confirme las diferencias de go.sum atómicamente con las importaciones.
• Etiquete las versiones de bibliotecas con semver. Los cambios que rompen requieren incrementos mayores o rutas /v2.
• Mantenga las dependencias directas mínimas y bajo control. Ejecute go mod why -m en las nuevas solicitudes.
• Aplique API Design Rules for Go Libraries antes de ampliar las exportaciones.
• Aplique Module & Dependency Rules en las auditorías de plataforma.

C - Concurrencia, seguridad y rendimiento

• Dé a cada goroutine una ruta de salida ligada a context o WaitGroup. Las fugas se manifiestan como bloqueos de apagado y OOM.
• Asigne un único propietario para cerrar cada canal. Los receptores nunca cierran; documente la propiedad en los tipos.
• Ejecute go test -race en paquetes que usan goroutines o mapas compartidos. Los fallos de concurrencia bloquean la fusión.
• Use Concurrency Rules Checklist para pools de trabajadores y manejadores de streaming.
• Valide la entrada externa en los límites de HTTP/gRPC. SQL parametrizado, límites de tamaño y plantillas seguras.
• Mantenga los secretos fuera del código fuente, los registros y los errores dirigidos al cliente. Cargue desde los secretos del orquestador en tiempo de ejecución.
• Ejecute govulncheck cuando cambien las dependencias. Clasifique las CVE alcanzables con actualización o aceptación fechada.
• Aplique Security Rules for Go Services antes de las puertas de lanzamiento.
• Perfil antes de fusionar las PR de optimización. Adjunte evidencia de CPU o asignación a las afirmaciones de mejora de velocidad.
• Elija por defecto código claro; optimice solo las rutas probadas y calientes. Registre las excepciones con benchmarks.
• Siga Performance Rules: When to Optimize para el trabajo de SLO.

D - Cultura de revisión y estándares de vida

• Empareje las reglas con Code Review Standards for Go Teams. El lint es el suelo; la revisión es el techo.
• Promueva una revisión repetida de detalles menores a un linter o ADR. Las reglas deben reducir la superficie de debate con el tiempo.
• Reaudite las reglas después de las actualizaciones menores de Go. Las nuevas comprobaciones de vet y los modernizadores de go fix cambian la aplicación.
• Diferencie explícitamente la estrictez de las bibliotecas frente a los servicios. Los módulos publicados se mantienen conservadores en las exportaciones.
• Enlace las plantillas de PR a este índice. Los autores se autocomprueban antes de solicitar una revisión.

Preguntas Frecuentes

Relacionado

• Effective Go as a Living Standard - explicador de la sección
• Go Rules Quickstart - introducción ejecutable
• Effective Go Rules Checklist - veinticinco modismos centrales
• Linting & Code Quality Best Practices - aplicación de la cadena de herramientas
• Errors as Values: Go's Error Philosophy - cultura de errores

Enlaces Externos Relacionados

• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Go Wiki – Learn - Recursos de aprendizaje curados por la comunidad.
• Go Official Website / Documentation - Centro de documentación principal.
• Learning Go (2nd Edition) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

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