Paquetes y Módulos: La Unidad de Distribución de Go
Go distribuye software como módulos versionados compuestos por paquetes.
//
Busca en todas las páginas de la documentación
Go distribuye software como módulos versionados compuestos por paquetes.
Esa combinación reemplazó el antiguo diseño GOPATH y te proporciona compilaciones reproducibles, actualizaciones conscientes de semver y una única historia de rutas de importación desde tu portátil hasta producción.
go.mod.go.mod, go.sum, Selección Mínima de Versión (MVS), internal/, versionado semántico de importaciones.go get eligió una versión particular./v2); el intercambio de granularidad fina todavía ocurre a nivel de paquete, no por archivo.replace/retract, y el grafo de compilación del comando go.Cada archivo .go declara package nombre y pertenece exactamente a un paquete en un directorio.
La ruta de importación es cómo otro código se refiere a ese paquete.
Para el código dentro de tu módulo, la ruta de importación es tu ruta de módulo más la ruta del directorio bajo la raíz del módulo.
Por ejemplo, el módulo example.com/widget con el archivo internal/api/handler.go se importa como example.com/widget/internal/api.
Un módulo es un árbol de paquetes enraizado en un directorio que contiene go.mod.
Ese archivo nombra el módulo (module example.com/widget), declara la versión mínima de Go y lista las versiones de dependencia requeridas.
Los consumidores registran tu módulo en su go.mod con una etiqueta semver (o pseudo-versión) y la cadena de herramientas lo descarga en la caché de módulos.
Los paquetes se refieren a compilación y visibilidad (identificadores exportados, reglas de internal/).
Los módulos se refieren a distribución y versionado (etiquetas, MVS, checksums).
Analogía: los paquetes son habitaciones en un edificio; el módulo es la dirección y los términos del contrato de arrendamiento para todo el edificio.
Cuando importas "github.com/foo/bar/baz", el compilador carga el paquete baz del módulo github.com/foo/bar en la versión seleccionada por MVS en tu go.mod.
El versionado semántico de importaciones requiere que los módulos principales v2+ incluyan el sufijo principal en la ruta del módulo (example.com/lib/v2), de modo que los cambios disruptivos no se actualicen silenciosamente bajo la misma cadena de importación.
La lista de compilación es el conjunto de versiones de módulos que el comando go utiliza para una compilación.
MVS elige la versión mínima de cada módulo que aún satisface cada require en el grafo.
Eso tiende a elegir actualizaciones conservadoras y mantiene las compilaciones predecibles en diferentes máquinas.
go.sum almacena hashes criptográficos del contenido de los módulos.
La cadena de herramientas verifica las descargas contra esas líneas para que un proxy comprometido no pueda sustituir código silenciosamente.
// go.mod (raíz del módulo)
module example.com/myapp
go 1.26
require (
github.com/google/uuid v1.6.0
golang.org/x/sync v0.10.0
)La directiva go es un límite mínimo de lenguaje/cadena de herramientas, no una dependencia en tiempo de ejecución.
Los paquetes bajo internal/ solo pueden ser importados por código dentro del árbol padre, lo que te permite refactorizar API privadas sin romper a los llamadores externos.
Los monorepos a menudo alojan un módulo o muchos.
Un solo módulo mantiene un go.mod y versionado compartido; múltiples módulos permiten a los equipos etiquetar y lanzar subsistemas de forma independiente a costa de más archivos go.mod y cableado de reemplazo/espacio de trabajo entre módulos.
Las bibliotecas publicadas para reutilización amplia deben mantener rutas de módulo estables, etiquetar lanzamientos y documentar rutas de migración a /v2.
Las aplicaciones pueden usar replace localmente o go.work durante el desarrollo sin publicar esas anulaciones.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Módulo único | Una línea de versión, CI simple | Grafos grandes, lanzamientos acoplados | Aplicaciones y bibliotecas pequeñas |
| Monorepo multi-módulo | Etiquetas independientes por área | Más mantenimiento de go.mod | Equipos de plataforma, infraestructura compartida |
Espacio de trabajo (go.work) | Ediciones locales entre módulos sin replace | No para consumidores publicados | Desarrollo activo multi-módulo |
Directorio vendor | CI aislado o fijado | Actualización manual, hinchazón del repositorio | Compilaciones reguladas u offline |
La publicación se realiza a través de etiquetas de control de versiones que coinciden con go list -m -versions.
Las pseudo-versiones llenan el vacío cuando dependes de commits sin etiquetar.
Retract marca etiquetas incorrectas sin eliminar el historial, dirigiendo las nuevas resoluciones lejos de lanzamientos rotos.
package main y algunos casos de la biblioteca estándar difieren; la ruta de importación es autoritativa para el compilador.Un paquete se compila conjuntamente a partir de uno o más archivos .go en un directorio.
Un módulo es la unidad versionada definida por go.mod que contiene esos paquetes y declara dependencias.
Las fuentes y los archivos zip de los módulos aterrizan en la caché de módulos, típicamente bajo $GOPATH/pkg/mod.
El código fuente de tu proyecto permanece en tu repositorio; la caché es de solo lectura desde la perspectiva de la cadena de herramientas.
El versionado semántico de importaciones mantiene las API incompatibles en rutas de importación distintas para que el código existente siga compilando hasta que opte por /v2.
Sí, para aplicaciones y bibliotecas.
Fija los checksums para que la CI y los compañeros de equipo verifiquen el mismo contenido del módulo.
No: un paquete por directorio (excepto los paquetes de prueba como package foo_test).
Divide los paquetes por subdirectorio.
Construye el grafo de requisitos a partir de todos los archivos go.mod involucrados y aplica la Selección Mínima de Versión para elegir la más antigua semver que aún satisfaga cada arista.
La ruta del módulo es el prefijo en go.mod.
La ruta de importación añade subdirectorios y puede incluir un sufijo de versión principal para módulos v2+.
Cuando los subsistemas se lanzan en diferentes cadencias, tienen diferentes conjuntos de consumidores o necesitan líneas semver aisladas.
Quédate con un solo módulo mientras los límites aún sean fluidos.
go get -u actualiza los requisitos hacia versiones más nuevas, pero las compilaciones normales todavía se resuelven a través de MVS y tus líneas require registradas.
Lee la diferencia antes de fusionar.
La biblioteca estándar se distribuye con la distribución de Go y no es un módulo descargable separado en compilaciones normales.
Todavía utiliza las mismas reglas de paquetes y rutas de importación.
No: la regla del directorio internal es aplicada por el compilador para las rutas bajo la raíz de tu módulo.
MVS eleva la versión seleccionada a la mínima que satisface ambas, a menos que añadas directivas replace o exclude.
No hay un enlazador de herencia de diamante como en otros ecosistemas.
cmd, internal y pkgVersiones de Pila: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, modernizadores de
go fix- verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 18 jul 2026