Reglas de Módulos y Dependencias
Semver, dependencias mínimas y límites de paquetes internos.
//
Busca en todas las páginas de la documentación
Semver, dependencias mínimas y límites de paquetes internos.
Referencia rápida para autores de módulos y equipos de plataforma que rigen la higiene de go.mod en servicios y bibliotecas.
go.mod, go.sum o rutas de importación.cmd/.govulncheck y automatización de actualizaciones de dependencias.go.work aún necesitan limpieza por módulo.| Regla | Comando / patrón | Señal de fallo |
|---|---|---|
| Tidy antes de fusionar | go mod tidy | Diferencia no vacía en go.mod/go.sum |
| Fijar versión de Go | go 1.26 coincide con la imagen de CI | Desajuste de toolchain local/CI |
| Una ruta de módulo por raíz de repositorio (predeterminado) | module example.com/foo | Módulos anidados accidentales sin go.work |
| Requerir reemplazos intencionales | replace con comentario + issue | replace permanente a forks |
| Retraer etiquetas incorrectas | Directiva retract en go.mod | Consumidores resuelven pseudo-versiones rotas |
| Vendorizar solo con política | go mod vendor + política de commit | Deriva de vendor sorpresa |
| Regla | Biblioteca | Aplicación / cmd |
|---|---|---|
| Etiquetas git Semver | v1.4.2 requerido | Etiquetas internas opcionales |
| Cambio de API que rompe compatibilidad | Mayor bump / ruta de módulo v2 | Refactorizar libremente dentro del límite de despliegue |
| Pre-lanzamiento | v0.y.z o internal/ | Ramas de características |
| Changelog | CHANGELOG.md o notas de lanzamiento | Notas de despliegue |
| Actualización del consumidor | go get example.com/foo@v1.4.2 | Imagen de compilación fija commit |
| Regla | Hacer | Evitar |
|---|---|---|
| Deps directas | Solo lo que importa el paquete | Copiar-pegar pilas de go get de publicaciones de blog |
| Conciencia indirecta | Revisar go mod why -m | Ignorar el bloat transitivo |
| Stdlib primero | net/http, encoding/json | Framework pesado para un solo manejador |
| Límites de interfaz | Adaptadores pequeños en los bordes | Importar ORM en paquetes de dominio |
| Deps de prueba | require solo de prueba en módulo separado o etiquetas de compilación | Importaciones de producción de testify en código de biblioteca |
| Escaneo de licencias | Lista blanca de licencias en la política de la plataforma | Deps transitivas AGPL no revisadas |
| Regla | Patrón | Aplicación |
|---|---|---|
| internal/ | example.com/foo/internal/bar | El compilador rechaza importadores externos |
| cmd/ | Solo main delgado | Sin lógica de negocio en main |
| Raíz de API pública | Paquetes estables en la raíz del módulo o pkg/ (elección del equipo) | Documentar en README |
| Sin colectores de utilidades | Dividir por dominio | Revisar nits sobre el crecimiento del paquete util |
| Ciclos de importación | Refactorizar a través de interfaces | Fallo de go build |
| Importaciones en blanco | Solo registro de efectos secundarios | El comentario explica el driver/plugin |
| Regla | Herramienta | Cadencia |
|---|---|---|
| Escaneo de vulnerabilidades | govulncheck ./... | Cada PR que toque dependencias |
| Integridad de suma | Comprometer go.sum | Nunca .gitignore go.sum |
| Módulos privados | GOPRIVATE, .netrc/token | Documentar en la incorporación |
| Exportación de SBOM | Artefacto del pipeline de compilación | Etiquetas de lanzamiento |
| Versiones de linter/acción de CI fijas | SHA o etiquetas semver | Política de cadena de suministro |
| Regla | Hacer | Evitar |
|---|---|---|
| Reemplazo local | go.work lista los módulos | Hacks de replace ../ registrados |
| Compilaciones de CI de cada módulo | Matriz o go work sync | Un módulo verde, otros rotos |
| Módulos publicables | Lanzamiento desde el directorio del módulo sin reemplazos solo de work | Publicar con rutas locales |
module example.com/widget
go 1.26
require (
golang.org/x/sync v0.10.0
)widget/
go.mod
widget.go // API exportada
internal/
store/
store.go // no importable fuera del módulo
cmd/
widgetctl/
main.go // main delgadoReparaciones temporales de forks con enlace a issue y fecha de eliminación.
No es un sustituto permanente de los lanzamientos upstream.
Opcional.
Las bibliotecas que publican para go get deben etiquetar lanzamientos semver.
La ruta de importación incluye el sufijo /v2; los cambios de comportamiento importantes se envían allí.
Ejecutar desde la raíz del módulo; comprometer tidy atómico con la importación que lo causó.
Investigar si el movimiento de tidy es constante - a menudo señala versiones flotantes.
Cada dependencia directa necesita un propietario y un plan de eliminación.
Prefiere stdlib y módulos pequeños y enfocados sobre mega-frameworks para bibliotecas.
Sí con GOPRIVATE y versionado documentado.
Trátalos como consumidores semver externos.
Compilaciones air-gapped, despliegues reproducibles, o política que requiere fuentes registradas.
Añade coste de mantenimiento en las actualizaciones.
Marcan etiquetas incorrectas para que go get las evite sin eliminar el historial de git.
Sí en el archivo del módulo principal; usa etiquetas de compilación para mantenerlas fuera de los binarios de producción.
Algunos equipos dividen la integración en módulos separados.
Úsalas para commits de pre-lanzamiento; prefiere lanzamientos etiquetados para pines de producción.
Documentado en Pseudo-versiones, replace y directivas retract.
go mod graph, go mod why -m, y análisis de alcance de govulncheck.
Bloquea fusiones en CVEs críticos alcanzables sin plan.
El objetivo y el subconjunto de stdlib difieren; mantén el módulo ordenado pero verifica que las importaciones se compilen en la toolchain del dispositivo.
Versiones de Stack: 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 - 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).
Revisado por Chris St. John·Última actualización: 19 jul 2026