El sistema de módulos de Go resuelve la gestión de dependencias de forma reproducible, pero hay situaciones que van más allá del flujo básico de go get: trabajar con varios módulos locales en paralelo, parchear una dependencia de terceros, retirar una versión ya publicada o acceder a repositorios privados sin exponer credenciales. Esta guía cubre esos casos con ejemplos reales.
Go Workspaces: múltiples módulos locales
Los workspaces (introducidos en Go 1.18) permiten trabajar con varios módulos locales simultáneamente sin usar hacks de replace en cada go.mod:
// Estructura de directorios // ~/proyectos/ // mi-app/ // go.mod (module github.com/acme/mi-app) // mi-libreria/ // go.mod (module github.com/acme/mi-libreria) // Crear el workspace en el directorio padre cd ~/proyectos go work init ./mi-app ./mi-libreria // Esto crea go.work: // go 1.21 // // use ( // ./mi-app // ./mi-libreria // ) // Ahora mi-app puede importar github.com/acme/mi-libreria // y usar la versión LOCAL, sin publicar nada
// Añadir un módulo al workspace existente go work use ./otro-modulo // Sincronizar dependencias del workspace go work sync
replace: parchear dependencias de terceros
replace sustituye una dependencia por una versión local o un fork. Útil para probar un parche antes de enviarlo upstream:
// go.mod module github.com/acme/mi-app go 1.21 require github.com/tercero/libreria v1.2.3 // Usar un fork local con el parche replace github.com/tercero/libreria => ../libreria-parcheada // O un fork en GitHub replace github.com/tercero/libreria => github.com/acme/libreria-fork v0.0.0-20240615000000-abcdef123456
Antes de publicar tu módulo, elimina los replace o tus usuarios tendrán problemas al descargarlo, ya que la ruta local no existirá en sus máquinas.
retract: retirar versiones publicadas
retract marca versiones que no deberían usarse por contener bugs graves o cambios incompatibles accidentales. Los usuarios que ya las usen recibirán una advertencia de go get:
// go.mod
module github.com/acme/mi-libreria
go 1.21
// Retirar versiones con bugs críticos
retract (
v1.3.0 // bug crítico de seguridad, usar v1.3.1
v1.2.0 // incompatibilidad accidental con Go 1.20
[v1.0.0, v1.1.0] // rango: retirar todas las versiones entre v1.0.0 y v1.1.0
)
// Para publicar la retracción, crea un nuevo tag git tag v1.3.1 git push origin v1.3.1 // Los usuarios verán: // go get github.com/acme/[email protected] // warning: module github.com/acme/[email protected]: retracted by module author: // bug crítico de seguridad, usar v1.3.1
Módulos privados con GOPRIVATE
GOPRIVATE indica a Go qué módulos no deben consultarse en el proxy público ni en la base de sumas de verificación:
// Variables de entorno export GOPRIVATE=github.com/mi-empresa/*,gitlab.mi-empresa.com/* export GONOSUMDB=github.com/mi-empresa/* export GONOPROXY=github.com/mi-empresa/* // Configurar permanentemente go env -w GOPRIVATE=github.com/mi-empresa/*
Proxy Athens para módulos privados
Athens es un proxy de módulos Go que puedes desplegar internamente. Cachea módulos públicos y sirve los privados con autenticación:
// Usar Athens como proxy principal (con fallback al proxy oficial) export GOPROXY=https://athens.mi-empresa.com|https://proxy.golang.org,direct // docker-compose.yml para Athens // version: '3' // services: // athens: // image: gomods/athens:latest // ports: // - "3000:3000" // environment: // - ATHENS_STORAGE_TYPE=disk // volumes: // - ./storage:/var/lib/athens
Comandos útiles de go mod
// Ver todas las dependencias (incluidas indirectas) go mod graph // Eliminar dependencias no usadas y añadir las que faltan go mod tidy // Descargar todas las dependencias al caché local go mod download // Ver qué versión de un paquete usas y por qué go mod why github.com/tercero/libreria // Actualizar todas las dependencias a la última versión minor/patch go get -u ./... // Actualizar a una versión concreta go get github.com/tercero/[email protected]