go.mod, go.sum y Selección de Versión Mínima

go.mod declara tu módulo y sus dependencias; go.sum bloquea sus checksums.

Juntos proporcionan builds reproducibles, y la Selección de Versión Mínima (MVS) elige versiones compatibles sin el comportamiento arbitrario de "el más nuevo gana".

Resumen

go.mod es el contrato de dependencias autoritativo para un módulo.

go.sum registra los hashes h1 de los archivos de módulos y go.mod que la toolchain ha visto.

MVS lee cada requisito en el grafo y selecciona la mínima versión semver que aún los satisface a todos.

Entender estas tres piezas explica la mayoría de las preguntas sobre go get, deriva de CI y "¿por qué está esta versión aquí?".

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

go mod init example.com/app
go get github.com/stretchr/testify@v1.9.0
go mod tidy
go list -m all

// go.mod (después de tidy)
module example.com/app
 
go 1.26
 
require (
    github.com/stretchr/testify v1.9.0
)

Cuándo usar esto:

• Al iniciar un nuevo módulo de servicio o librería.
• Al auditar contra qué versiones construye realmente la CI.
• Al limpiar líneas require no utilizadas después de una refactorización (go mod tidy).
• Al investigar un aumento de versión de una dependencia transitiva.

Ejemplo de Trabajo

example.com/app/
  go.mod
  go.sum
  main.go

// main.go
package main
 
import (
    "fmt"
    "github.com/google/uuid"
)
 
func main() {
    fmt.Println(uuid.NewString())
}

go get github.com/google/uuid@v1.6.0
go mod tidy
cat go.mod
grep uuid go.sum

Lo que esto demuestra:

• require registra las dependencias directas que importas (y a veces herramientas).
• go.sum gana líneas como github.com/google/uuid v1.6.0 h1:... para verificación de contenido.
• go list -m all muestra los módulos directos y transitivos en la lista de compilación.

Profundización

Cómo Funciona

1. Añades o cambias importaciones (o ejecutas go get).
2. El comando go carga los archivos go.mod de tu módulo y dependencias recursivamente.
3. MVS calcula una versión por ruta de módulo que satisface cada arista de require.
4. Las descargas se verifican contra go.sum; las líneas faltantes pueden añadirse en la primera obtención de confianza.
5. Las compilaciones compilan paquetes desde la caché de módulos en esas versiones.

MVS no es un solucionador global que minimiza las actualizaciones totales.

Es local por ruta de módulo: elige la versión más antigua que aún cumpla todos los mínimos declarados.

Directivas de go.mod

Las dependencias indirectas aparecen con comentarios // indirect después de go mod tidy cuando no las importas directamente.

Líneas de go.sum

Cada versión de módulo típicamente tiene:

github.com/foo/bar v1.2.3 h1:<hash>
github.com/foo/bar v1.2.3/go.mod h1:<hash>

La línea /go.mod hashea el archivo go.mod de la dependencia.

Haz commit de go.sum para aplicaciones y librerías para que la CI verifique el mismo contenido.

Ejemplo de MVS

Si el módulo A requiere C v1.2.0 y el módulo B requiere C v1.4.0, MVS selecciona C v1.4.0 (la mínima que satisface el requisito más alto).

Si ambos requirieran v1.2.0, obtendrías v1.2.0 incluso cuando v1.9.0 exista en el proxy.

Notas de Go

# Ver por qué aparece un módulo
go mod why -m github.com/some/transitive
 
# Grafo de requisitos
go mod graph | head
 
# Verificar sumas sin red cuando sea posible
go mod verify

// directiva de toolchain (opcional, Go 1.21+)
// go.mod
module example.com/app
 
go 1.26
 
toolchain go1.26.0

Errores Comunes

• Editar go.mod manualmente sin go mod tidy deja 'requires' huérfanos. Prefiere comandos que actualicen tanto go.mod como go.sum.
• Asumir que go get -u siempre ayuda puede introducir actualizaciones amplias; revisa las diferencias y ejecuta pruebas.
• Borrar go.sum para "arreglar" errores elimina el rastro de auditoría; regenera con tidy y get intencionales en su lugar.
• // indirect no significa no utilizado - significa que ningún paquete en tu módulo lo importa directamente; aún podrías necesitarlo transitivamente.
• Los módulos privados necesitan GOPRIVATE y credenciales VCS - la base de datos de checksums puede omitirse para rutas privadas.

Alternativas

• Vendor (go mod vendor) - Copia el código fuente a vendor/ para CI offline o hermética.
• Workspace (go.work) - Sobrescribe locales sin hacer commit de replace en cada módulo.
• Fijar con go get module@v en CI - Actualizaciones programadas en lugar de usar @latest flotante en main.

Preguntas Frecuentes

Relacionados

• Paquetes y Módulos: La Unidad de Distribución de Go - Visión general de los módulos
• Pseudo-Versiones, Directivas replace y retract - Sobrescribe más allá de require
• go work: Modo Workspace para Repositorios Multi-Módulo - Builds locales multi-módulo
• Conceptos Básicos de Paquetes y Módulos - Comandos tidy, get y list

Versiones de Stack: Esta página fue escrita para Go 1.26.x (Green Tea GC por defecto, go fix modernizadores - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).