Módulos, go.mod y gestión de dependencias

¿Qué es un módulo en Go?

Un módulo es la unidad de distribución y versionado de código en Go. Un módulo es un árbol de directorios con un fichero go.mod en la raíz que declara:

• El nombre del módulo (su ruta de importación)
• La versión mínima de Go requerida
• Las dependencias (otros módulos) con sus versiones exactas

mi-proyecto/
├── go.mod        ← raíz del módulo
├── go.sum        ← hashes de integridad
├── main.go
└── calculadora/
    ├── suma.go
    └── suma_test.go

Inicializar un módulo

mkdir mi-proyecto && cd mi-proyecto
go mod init github.com/usuario/mi-proyecto

El fichero go.mod generado:

module github.com/usuario/mi-proyecto

go 1.23

El nombre del módulo determina cómo se importan sus paquetes:

// En main.go
import "github.com/usuario/mi-proyecto/calculadora"

Crear y usar paquetes

Cada directorio es un paquete. Los identificadores exportados (con mayúscula) son accesibles desde otros paquetes:

// calculadora/suma.go
package calculadora

// Sumar es una función exportada
func Sumar(a, b int) int {
    return a + b
}

// resto es privada al paquete
func resto(a, b int) int {
    return a % b
}

// main.go
package main

import (
    "fmt"
    "github.com/usuario/mi-proyecto/calculadora"
)

func main() {
    fmt.Println(calculadora.Sumar(3, 4)) // 7
}

Añadir dependencias externas

# Añadir la última versión compatible
go get github.com/gin-gonic/gin

# Versión específica
go get github.com/gin-gonic/gin@v1.9.1

# Actualizar todas las dependencias
go get -u ./...

# Eliminar dependencias no utilizadas y añadir las que falten
go mod tidy

El go.mod actualizado:

module github.com/usuario/mi-proyecto

go 1.23

require github.com/gin-gonic/gin v1.9.1

El fichero go.sum

go.sum contiene los hashes SHA-256 de todos los módulos descargados. Go verifica estos hashes antes de usar una dependencia para detectar modificaciones inesperadas:

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YRdiu...

Nunca edites go.sum manualmente. Sí debes incluirlo en el control de versiones.

Convención de directorios

mi-proyecto/
├── go.mod
├── go.sum
├── cmd/                    # puntos de entrada (main)
│   ├── servidor/
│   │   └── main.go
│   └── worker/
│       └── main.go
├── internal/               # paquetes privados del módulo
│   ├── repositorio/
│   │   └── usuario.go
│   └── servicio/
│       └── auth.go
└── pkg/                    # librería reutilizable externamente
    └── validacion/
        └── email.go

• cmd/: un subdirectorio por ejecutable, cada uno con su main.go
• internal/: solo importable desde el propio módulo (protegido por el compilador)
• pkg/: código de biblioteca pensado para ser importado por otros módulos

Workspaces: desarrollar múltiples módulos localmente

Los workspaces (go work) evitan tener que publicar un módulo para probarlo desde otro:

# Estructura
├── modulo-a/   (go.mod: module github.com/usuario/modulo-a)
├── modulo-b/   (go.mod: module github.com/usuario/modulo-b, usa modulo-a)
└── go.work

# Inicializar workspace
go work init ./modulo-a ./modulo-b

Fichero go.work:

go 1.23

use (
    ./modulo-a
    ./modulo-b
)

Los cambios locales en modulo-a son visibles inmediatamente desde modulo-b.

Compilación cruzada

Go compila binarios estáticos para cualquier plataforma sin herramientas adicionales:

# Lista de plataformas soportadas
go tool dist list

# Compilar para Linux desde cualquier sistema
GOOS=linux GOARCH=amd64 go build -o app-linux ./cmd/servidor

# Para macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o app-macos ./cmd/servidor

# Para Windows
GOOS=windows GOARCH=amd64 go build -o app.exe ./cmd/servidor

Herramientas esenciales del toolchain

go build ./...        # compilar todo el módulo
go test ./...         # ejecutar todas las pruebas
go vet ./...          # análisis estático
go fmt ./...          # formatear código
go doc fmt Println    # documentación de una función
go list -m all        # listar todas las dependencias
go mod graph          # grafo de dependencias
go mod verify         # verificar integridad de go.sum