Go Modules es el sistema oficial de gestión de dependencias desde Go 1.16. Reemplaza definitivamente al antiguo GOPATH y garantiza builds reproducibles: cada versión de cada dependencia queda registrada con su hash criptográfico, de modo que todos los desarrolladores del equipo y el CI descargan exactamente los mismos bytes.
go.mod: el fichero central
El fichero go.mod declara el módulo y sus dependencias directas. Se crea con go mod init:
go mod init github.com/tuusuario/miapp
Un go.mod típico tiene este aspecto:
module github.com/tuusuario/miapp
go 1.22
require (
github.com/gin-gonic/gin v1.10.0
github.com/jmoiron/sqlx v1.4.0
)
require (
// dependencias indirectas (de tus dependencias)
golang.org/x/net v0.25.0 // indirect
)
go.sum: verificación de integridad
go.sum contiene los hashes SHA-256 de cada versión de cada módulo descargado. No lo edites a mano; lo gestiona el toolchain. Inclúyelo siempre en el control de versiones:
github.com/gin-gonic/gin v1.10.0 h1:nnt/K9BcVpu8tKQLzTMJCi7gzRzg4i5yYFCPYZ7sAY= github.com/gin-gonic/gin v1.10.0/go.mod h1:9hINb2EeHSEi/K9sZ9Ph0c8VFSZxSEBXFuCGYVLFZE=
go get: añadir y actualizar dependencias
# añadir una dependencia go get github.com/gin-gonic/[email protected] # actualizar a la última versión go get github.com/gin-gonic/gin@latest # actualizar todas las dependencias a su última patch go get -u ./... # descargar sin añadir al go.mod (para herramientas) go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go mod tidy: limpiar dependencias
go mod tidy añade las dependencias que faltan en go.mod y elimina las que ya no se usan. Ejecútalo antes de cada commit:
go mod tidy
Versiones principales: v2 y más allá
Cuando un módulo lanza una versión mayor con cambios incompatibles, el import path cambia para incluir la versión. Esto permite que distintas versiones mayores coexistan en el mismo binario:
// v1: github.com/foo/bar
// v2: github.com/foo/bar/v2
import (
barv1 "github.com/foo/bar"
barv2 "github.com/foo/bar/v2"
)
La directiva replace
replace sustituye un módulo por otro, útil para probar un fork local sin publicarlo:
replace github.com/foo/bar => ../bar-local
También se usa para forzar una versión específica de una dependencia transitiva problemática.
Workspaces con go.work
Los workspaces (Go 1.18+) permiten trabajar con varios módulos locales a la vez sin tocar los go.mod de producción:
go work init go work use ./miapp ./biblioteca-local
El fichero go.work resultante le dice al toolchain que resuelva las importaciones de esos módulos usando el código local en lugar del publicado en el proxy. Es ideal para desarrollar una librería y una app que la consume en paralelo.
Repositorios privados
Para módulos en repositorios privados que no están en el proxy público de Go, declara los patrones en GOPRIVATE:
export GOPRIVATE=github.com/tu-empresa/* go get github.com/tu-empresa/modulo-interno
Go saltará el proxy y el checksum database para esas rutas y accederá directamente al VCS usando las credenciales de tu sistema.