Módulos de Go: go.mod, go.sum y el sufijo de versión mayor

Qué es

La referencia de Go Modules (Go Modules Reference) define un módulo como un conjunto de paquetes que se publican juntos, con un archivo go.mod en su raíz que indica la ruta del módulo, la directiva go (la versión mínima de Go, de cumplimiento obligatorio y no meramente orientativo desde Go 1.21), las líneas require y, opcionalmente, las directivas replace, exclude, retract y toolchain. Las versiones siguen Semantic Versioning 2.0.0 con el prefijo v. La referencia describe la selección de versión mínima: el comando go recorre el grafo de requisitos y compila con la versión más alta a la que cada módulo es requerido; nunca elige una versión más reciente solo porque exista, de modo que la lista de compilación se puede reproducir únicamente a partir de go.mod. go.sum registra los hashes criptográficos de cada módulo utilizado, que se comprueban en la descarga y, por defecto, también contra la base de datos pública de sumas de verificación sum.golang.org.

La regla con la que más tropiezan quienes se inician es el sufijo de versión mayor. La referencia enuncia la regla de compatibilidad de importación (si un paquete antiguo y uno nuevo tienen la misma ruta de importación, el paquete nuevo debe ser retrocompatible con el antiguo) y por ello exige que las versiones mayores 2 y superiores lleven el sufijo en la ruta del módulo: example.com/lib/v2. Las versiones v0 y v1 no llevan sufijo; v0 no ofrece ninguna promesa de compatibilidad. Las etiquetas v2 o superiores sin archivo go.mod aparecen con +incompatible.

Por qué importa

pip y npm prefieren la versión más reciente permitida y necesitan un archivo de bloqueo o de fijación para ser reproducibles; Go resuelve a la versión más baja que satisface a todos y recalcula la misma lista en cada comando. Como lib y lib/v2 son rutas de importación distintas, ambas pueden coexistir en la misma compilación, y actualizar una versión mayor consiste en buscar y reemplazar importaciones, en lugar de provocar un conflicto en el resolvedor.

Cómo aplicarlo

• Ejecuta go mod tidy tras cambiar las importaciones; añade los requisitos que faltan, elimina los que no se usan y actualiza go.sum; haz commit de ambos archivos.
• Actualiza una dependencia concreta con go get example.com/lib@v1.4.0; para pasar a una nueva versión mayor, importa la ruta con el sufijo.
• Al publicar la v2 de tu propio módulo, cambia la línea module para que termine en /v2 antes de etiquetar; el blog sobre módulos v2 recomienda un subdirectorio de versión mayor (v2/go.mod) en lugar de ramas separadas.
• Usa replace solo en el módulo principal y para desarrollo local; la referencia indica que se ignora en los archivos go.mod de otros módulos.
• Prefiere retract a borrar una etiqueta defectuosa; la etiqueta permanece en la base de datos de sumas de verificación.

Trampas

Etiquetar v2.0.0 en un módulo cuya ruta carece del sufijo hace que el comando go rechace la versión. La directiva go es un requisito estricto desde Go 1.21: una toolchain más antigua que la versión declarada cambia a una más reciente o se niega a compilar, en lugar de limitarse a mostrar una advertencia. go.sum no es un archivo de bloqueo: verifica lo que eligió la selección de versión mínima.