Un módulo de Go es la unidad que agrupa un proyecto y sus dependencias. En la práctica, es el punto de partida para compilar, versionar y compartir código Go moderno.
Durante muchos años, la gestión de dependencias en Go fue… complicada. Existía una variable de entorno llamada GOPATH que obligaba a tener todo tu código en una carpeta específica del sistema. Era rígido y doloroso.
Go introdujo los módulos en la versión 1.11 y, desde Go 1.16, el modo de módulos está activado por defecto.
Ya no importa dónde guardemos el código. La definición del módulo gira alrededor de go.mod y, cuando hay dependencias descargadas, go.sum registra las sumas necesarias para verificarlas.
Vamos a ver qué contiene cada archivo y cómo mantenerlos con las herramientas de Go.
El archivo go.mod
El archivo go.mod es el corazón de tu proyecto. Define quién eres y qué necesitas.
Cuando ejecutas go mod init nombre-del-proyecto, se crea este archivo. Veamos un ejemplo real:
// 1. Nombre del módulo (generalmente una URL de repo)
module github.com/luisllamas/mi-api
// 2. Versión mínima de Go requerida
go 1.25.0
// 3. Lista de dependencias directas e indirectas
require (
github.com/gin-gonic/gin v1.9.1
github.com/google/uuid v1.3.0
golang.org/x/sys v0.8.0 // indirect
)Anatomía
- module: Es el identificador único. Si vas a subir tu código a GitHub, debe coincidir con la URL (
github.com/usuario/repo). Esto permite que otros importen tu código usándola. - go:** la versión mínima de Go requerida y la semántica del lenguaje que usa el módulo. Desde Go 1.21, una herramienta anterior rechaza un módulo que exige una versión posterior.
- require:** declara versiones mínimas de otros módulos. Go resuelve el conjunto final mediante Minimal Version Selection.
¿Ves ese comentario // indirect? Significa que tú no has importado esa librería directamente, pero una de tus dependencias la necesita para funcionar. Go la gestiona por ti.
El archivo go.sum: sumas de verificación
Esta parte suele generar confusión. Si vienes de Node.js, pensarás que go.sum es como package-lock.json. En parte sí, pero su función principal es la Integridad Criptográfica.
El archivo go.sum no es un archivo de bloqueo ni un árbol de dependencias. Contiene sumas de verificación del contenido de módulos y de sus archivos go.mod que las herramientas han necesitado descargar.
github.com/gin-gonic/gin v1.9.1 h1:4... (hash)
github.com/gin-gonic/gin v1.9.1/go.mod h1:h... (hash)¿Para qué sirve?
Imagina que hoy te descargas la librería uuid v1.3.0.
Mañana, un hacker (o un mantenedor malintencionado) cambia el código de la versión v1.3.0 en GitHub para inyectar un virus, pero mantiene el mismo número de versión.
Cuando tus compañeros (o el servidor de CI/CD) intenten descargar esa versión, Go comparará el hash de lo que descargan con lo que dice tu go.sum. Si no coinciden, Go bloqueará la descarga y lanzará una alerta de seguridad.
El archivo go.sum debe subirse al repositorio. Junto con go.mod, permite verificar que el contenido descargado coincide con el conocido por el proyecto. Puede conservar entradas de versiones que ya no están en la lista de compilación, y go mod tidy eliminará las innecesarias.
Flujo de trabajo diario
En el día a día, apenas tocarás estos archivos a mano. Usarás los comandos de la CLI de Go.
Añadir una dependencia con go get
Si quieres usar una librería externa, como el framework web “Fiber”:
go get github.com/gofiber/fiber/v2@latestEsto actualiza go.mod con una versión que contiene el paquete solicitado. Las herramientas descargarán los módulos necesarios en la caché y actualizarán go.sum.
La opción -u también intenta actualizar dependencias directas o indirectas del paquete indicado. No la añadas por costumbre si solo quieres incorporar una librería concreta; revisa siempre los cambios de go.mod y go.sum.
Importar el paquete en el código
Una vez descargado, lo usas en tu .go:
import "github.com/gofiber/fiber/v2"Ajustar el módulo con go mod tidy
Este es el comando que usarás constantemente.
A medida que programas, a veces borras un import porque dejas de usar una librería, o añades uno nuevo a mano. El archivo go.mod puede quedar “sucio” (con dependencias que ya no usas o que faltan).
El comando go mod tidy hace limpieza general:
- Añade las dependencias que te falten.
- Borra las dependencias que ya no uses en tu código.
- Actualiza el
go.sum.
Ejecuta go mod tidy después de cambiar importaciones y revisa su diff antes de confirmar los cambios.
Versionado semántico y actualizaciones
Go se toma muy en serio el Versionado Semántico (Major.Minor.Patch).
- v1.0.0 a v1.9.9: comparten la misma ruta de módulo. El versionado semántico promete compatibilidad, pero una actualización sigue mereciendo pruebas y revisión.
- v2.0.0 (Major Upgrade): Aquí cambia la película.
Si una librería lanza la versión v2, Go considera que es una librería diferente con un path de importación diferente.
// Versión 1
import "github.com/usuario/mi-lib"
// Versión 2 (Rompe compatibilidad)
import "github.com/usuario/mi-lib/v2"Las rutas distintas permiten que en un mismo grafo convivan la v1 y la v2 si dos partes del programa las necesitan.
¿Dónde está la carpeta de dependencias?
Go guarda las dependencias en una caché compartida indicada por GOMODCACHE (por defecto, $GOPATH/pkg/mod).
Esto tiene dos ventajas brutales:
- Ahorro de disco: varios proyectos pueden reutilizar la misma versión descargada de un módulo.
- Velocidad: si una versión ya está en caché, no hace falta descargarla de nuevo.
