Prácticas recomendadas para bibliotecas esenciales de Go
Un resumen condensado de las 25 prácticas más importantes para bibliotecas esenciales, extraídas de cada página de esta sección.
//
Busca en todas las páginas de la documentación
Un resumen condensado de las 25 prácticas más importantes para bibliotecas esenciales, extraídas de cada página de esta sección.
Primero la biblioteca estándar: Utiliza log/slog, net/http y database/sql antes de añadir módulos; documenta la brecha de capacidad cuando importes.
Una biblioteca por preocupación: Elige un logger, un router y un cargador de configuración por servicio; las herramientas duplicadas inflan la incorporación y la superficie de vulnerabilidades (CVE).
Revisa las diferencias de go.mod: Trata las nuevas líneas require como código de producción en la revisión de PR; ejecuta go mod tidy antes de fusionar.
Ejecuta govulncheck en CI: Escanea el grafo completo de módulos después de los cambios de dependencias; bloquea las fusiones en rutas críticas que defina tu política.
Verifica los archivos LICENSE: Confirma la compatibilidad con BSD/MIT/Apache antes de importar; revisión legal para LGPL o términos inusuales.
Inspecciona las señales de mantenimiento: Favorece las bibliotecas con lanzamientos recientes, problemas de respuesta y propiedad clara sobre las estrellas estancadas de GitHub.
Mide la profundidad transitiva: Ejecuta go list -m all al evaluar las importaciones; los grafos poco profundos envejecen mejor que los forks sorpresa.
Mantén las bibliotecas en los bordes: Los paquetes de dominio aceptan interfaces; zap, chi y viper se detienen en los manejadores, main y internal/config.
Inyecta loggers: Pasa *slog.Logger o *zap.Logger desde main; evita los valores predeterminados a nivel de paquete que las pruebas no puedan anular.
Estabiliza los nombres de los campos de log: Usa claves consistentes (trace_id, err, user_id) en todos los servicios para que las migraciones entre zap, zerolog y slog no rompan las consultas.
Por defecto, los nuevos servicios usan slog: Adopta zap o zerolog solo cuando las pruebas de rendimiento en manejadores reales demuestren cuellos de botella de asignación.
Carga la configuración una vez en main: Descodifica viper o envconfig en structs tipados; nunca disperses viper.GetString por los paquetes de negocio.
Valida los secretos requeridos al inicio: Falla rápidamente cuando los DSN o las claves API estén vacíos; no descubras la configuración faltante con el primer tráfico.
Documenta las tablas de variables de entorno: Refleja las etiquetas de struct en el README y los comentarios de Helm para que los operadores conozcan las claves requeridas sin leer el código.
Usa testify solo en pruebas: Mantén las aserciones en _test.go; los consumidores de la biblioteca no deben heredar testify transitivamente de tu API.
Prefiere interfaces pequeñas para mocks: Define interfaces de uno o dos métodos en el consumidor; genera mocks con mockery solo cuando los contratos de llamada importen.
Regenera Wire después de cambios en los proveedores: Ejecuta wire ./... en CI y falla ante diferencias obsoletas en wire_gen.go cuando los constructores se muevan.
Divide los conjuntos de inyectores de Wire: Usa conjuntos de proveedores separados por binario (API, worker) en lugar de un único inicializador de grafo maestro.
Valida en el borde HTTP: Ejecuta validator en los DTO después de la decodificación JSON; mantén los invariantes de negocio en los servicios, no solo en las etiquetas.
Ejecuta migraciones en trabajos de despliegue: Aplica up de golang-migrate antes de que el nuevo código sirva tráfico; nunca migres dentro de los manejadores de solicitudes.
Mantén sincronizado el esquema de sqlc: Apunta sqlc a la misma carpeta de migración que usa CI; regenera Go cuando cambien las consultas o las columnas.
Protege la cardinalidad de Prometheus: Etiqueta las métricas con patrones de ruta, no con URLs crudas con IDs; limita las dimensiones de las etiquetas en los ADR.
Cierra los exportadores de OTel en SIGTERM: Llama a TracerProvider.Shutdown durante el vaciado gradual para que los spans se envíen antes de salir.
Expón /metrics de forma segura: Escanea en un puerto de administración o detrás de una política de red; no publiques métricas operativas en Internet sin autenticación.
Registra las elecciones de bibliotecas en los ADR: Documenta por qué chi sobre Gin, slog sobre zap, o sqlc sobre ORM para que los equipos futuros entiendan las restricciones y las rutas de migración.
Después de las principales versiones de Go y cuando los avisos de seguridad afecten a tu grafo; al menos trimestralmente para las pilas propiedad de la plataforma.
Primero la biblioteca estándar más dependencias mínimas; mantiene las compilaciones rápidas, el radio de explosión de CVE pequeño y la incorporación predecible.
Prefiere listas blancas con excepciones a través de ADR en lugar de prohibiciones ad hoc por servicio sin gobernanza.
Las bibliotecas enfrentan límites de dependencias transitivas más estrictos; los consumidores heredan todo tu grafo.
Cuando la lógica tiene aproximadamente treinta líneas o menos, ha sido revisada por seguridad y es poco probable que necesite correcciones del upstream; documenta la decisión del fork.
Sí, para la higiene de logging y configuración; las CLI pueden omitir los routers HTTP y las métricas a menos que expongan servidores.
Las reglas semver de módulos complementan estas prácticas de bibliotecas; usa ambas en las plantillas de PR.
Claves de campo inconsistentes entre servicios, lo que rompe los dashboards durante las migraciones de bibliotecas.
Solo cuando la política lo requiera; el vendoring no elimina la necesidad de verificar las versiones y ejecutar govulncheck.
Los artículos de slog, Prometheus RED y trazado OTel profundizan más; esta sección nombra las selecciones de bibliotecas en el borde.
Versiones de pila: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 19 jul 2026