go.mod es el manifiesto que define la identidad de tu proyecto y establece qué versiones de qué dependencias necesita para funcionar. Es el núcleo del sistema de módulos de Go. Por su parte, go.sum actúa como una lista de verificación de seguridad que contiene los hashes criptográficos de cada módulo descargado.
El diseño de Go separa la resolución de versiones (qué versión necesito, definida en go.mod) de la integridad del contenido (que el código descargado no haya sido alterado, asegurada por go.sum). Cuando ejecutas go mod tidy, el compilador limpia tu árbol de dependencias, eliminando lo que no usas y añadiendo lo que falta. Si intentas usar una dependencia sin haberla declarado o sin que esté reflejada en el manifiesto, el comando go build fallará. Si go.sum no coincide con lo que el comando go get intenta descargar, el proceso se detendrá por seguridad para evitar ataques de suplantación de código.
package main
import (
"fmt"
"time"
// Esta dependencia externa debe estar declarada en go.mod
"github.com/google/uuid"
)
// Este ejemplo simula una aplicación que genera IDs únicos para auditoría.
func main() {
// Generamos un UUID v4 usando la librería externa.
// Para que esto funcione, primero debemos ejecutar:
// 1. go mod init mi-proyecto
// 2. go mod tidy
id := uuid.New()
fmt.Printf("[%s] Generando identificador único...\n", time.Now().Format(time.RFC3339))
fmt.Printf("ID generado con éxito: %s\n", id)
}
Para que este código funcione, no basta con escribirlo. Primero, debes inicializar el módulo con go mod init mi-proyecto. Al intentar ejecutarlo, Go detectará que github.com/google/uuid no está en tu sistema y lo buscará. Al ejecutar go mod tidy, Go descargará la librería, la añadirá a tu archivo go.mod bajo una directiva require y calculará su “huella digital” para guardarla en go.sum.
Al revisar tu directorio después de esto, verás que go.mod contiene la línea go 1.23 (la versión mínima requerida) y la declaración require github.com/google/uuid v1.6.0. Es importante notar que go.sum no solo guarda el hash del código fuente, sino también un hash para el archivo go.mod de la propia dependencia; esto es lo que garantiza que ni siquiera la lista de dependencias de tu librería favorita haya sido manipulada.
El archivo go.mod es el que siempre debes subir a tu repositorio. Si no lo haces, nadie (ni tus compañeros ni el servidor de CI/CD) podrá compilar tu proyecto de forma consistente. go.sum también debe committearse: es tu garantía de que el código que probaste en tu máquina local es exactamente el mismo que se compilará en producción.
El error frecuente
Un error común es intentar “editar” manualmente la versión de una dependencia directamente en go.mod para forzar una actualización. Esto suele corromper el estado de tu módulo. Si intentas hacer esto, lo más probable es que te encuentres con un error de checksum mismatch la próxima vez que intentes descargarla.
Si alguien altera un tag de una versión (por ejemplo, alguien sube un commit malicioso a la etiqueta v1.2.3 de una librería), el hash calculado por go.sum no coincidirá con el nuevo contenido descargado. Go detectará la discrepancia y bloqueará la compilación. En ese caso, la solución no es simplemente borrar el archivo, sino entender que la integridad de tu cadena de suministro ha sido comprometida. Para corregir problemas de limpieza, siempre confía en go mod tidy en lugar de editar el archivo go.mod a mano.
N° 98