Patrones de Git para Monorepos con go work
Un único repositorio Git puede alojar múltiples módulos de Go coordinados por go.work durante el desarrollo.
//
Busca en todas las páginas de la documentación
Un único repositorio Git puede alojar múltiples módulos de Go coordinados por go.work durante el desarrollo.
El historial de Git se mantiene unificado mientras cada módulo conserva su propio go.mod, etiquetas y grafo de consumidores.
Los Monorepos son adecuados para equipos de plataforma que envían bibliotecas y servicios compartidos juntos.
Usa go.work localmente para reemplazar las directivas replace entre módulos en los archivos go.mod confirmados.
Etiqueta y haz CI de cada módulo explícitamente para que los proxies y consumidores resuelvan las versiones correctas.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
# Diseño del repositorio
# services/api/go.mod
# libs/auth/go.mod
cd repo-root
go work init ./services/api ./libs/auth
go work use -r . # opcional: descubrir módulos
# Desarrollar entre módulos
cd services/api
go test ./...
# Validar vista de publicación (sin espacio de trabajo)
GOWORK=off go test ./...Cuándo usar esto:
replace específicas de la máquina en ramas compartidas.replace de go.mod de otros.acme-platform/
go.work
go.work.sum
libs/telemetry/go.mod # github.com/acme/telemetry
services/billing/go.mod # github.com/acme/billing
// go.work
go 1.26
use (
./libs/telemetry
./services/billing
)# Cambiar la API de telemetry y arreglar billing en una rama
git switch -c feat/telemetry-batch
# editar libs/telemetry/...
# editar services/billing/...
go test ./...
cd services/billing && GOWORK=off go test ./...
git add libs/telemetry services/billing go.work go.work.sum
git commit -m "telemetry: añadir exportación por lotes; billing: adoptar API por lotes"
git push -u origin feat/telemetry-batchEtiqueta solo el módulo de la biblioteca al lanzar para consumidores externos:
git switch main && git pull --ff-only
cd libs/telemetry
git tag -a v0.4.0 -m "telemetry v0.4.0"
git push origin v0.4.0Lo que esto demuestra:
go.work enlaza reemplazos locales implícitamente durante el desarrollo.GOWORK=off simula la experiencia de los consumidores de módulos.go.mod en la raíz de un subdirectorio.go.work en la raíz del repositorio lista los directorios de módulos en directivas use.go prefiere los módulos del espacio de trabajo sobre las versiones proxy para esas rutas.go.mod en una PR.go.work.sum registra checksums para la resolución del espacio de trabajo, similar a go.sum.
Confirma go.work cuando todo el equipo comparte la disposición del espacio de trabajo.
Mantén experimentos personales en go.work no rastreado o en la anulación de entorno GOWORK.
| Patrón | Propósito |
|---|---|
| Etiquetas de PR con ámbito de ruta | Mostrar qué módulos afecta una PR |
| CODEOWNERS por módulo | Dirigir la revisión al equipo propietario |
Prefijo de etiqueta telemetry/v0.4.0 | Desambiguar etiquetas multi-módulo (documentar en README) |
Matriz de CI por go.mod | Retroalimentación más rápida en repositorios grandes |
GOWORK=off trabajo de lanzamiento | Verificar el grafo de módulos publicable |
| Mecanismo | ¿Confirmado en main compartido? | Impacto en el consumidor |
|---|---|---|
go.work | Ayuda opcional para el equipo en desarrollo | Ninguno (no se publica) |
replace en go.mod | Evitar para rutas locales | Rompe go get para usuarios externos |
require versionado | Sí | Ruta normal del consumidor |
strategy:
matrix:
module: [libs/telemetry, services/billing]
steps:
- run: cd ${{ matrix.module }} && GOWORK=off go test ./...El trabajo del espacio de trabajo raíz aún puede ejecutar go test ./... desde go.work para la confianza en la integración.
replace ../libs confirmadas - Rompen clones externos. Solución: go.work para desarrollo local; requerir versiones semver en main.internal/ abarca módulos - El compilador aplica por raíz de módulo. Solución: código compartido en paquetes publicados o un solo módulo hasta que la división sea real.GOWORK=off en la CI de lanzamiento - Envía sorpresas del grafo solo del espacio de trabajo. Solución: modo off obligatorio antes de etiquetar.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Módulo único | Una línea de lanzamiento, grafo simple | Semver independiente por subsistema |
| Multi-repo | Límites de equipo duros | Cambios frecuentes atómicos transversales |
| Bazel / build personalizado | Orquestación políglota no-Go | Los flujos de trabajo estándar de go son suficientes |
| Submódulos Git | Separación heredada | Se prefieren las ventajas ergonómicas de los módulos Go |
Sí, cuando todos los desarrolladores usan el mismo conjunto de módulos diariamente.
No, cuando es un superconjunto personal de módulos; usa un archivo local no rastreado en su lugar.
Por la ruta del módulo en cada go.mod, no por la raíz del repositorio.
go get github.com/acme/telemetry@v0.4.0 obtiene solo ese subárbol de módulo.
Sí.
Ejecuta las pruebas con el espacio de trabajo activado y GOWORK=off para cada módulo afectado antes de fusionar.
Rutas de módulo separadas (/v2) y etiquetas por versión mayor.
El espacio de trabajo puede incluir ambas líneas durante la migración.
No.
Anula la resolución localmente; go.mod todavía lista los require semver previstos para los consumidores.
Extrae el historial con filter-repo o copia el subárbol, publica la nueva ruta del módulo, retrae las rutas antiguas si es necesario.
Planifica la migración de rutas de importación en el changelog.
Posible en cada raíz de módulo.
Actualiza vendor en la PR que actualiza las dependencias de ese módulo solamente.
Los mismos patrones de trunk que los repositorios de un solo módulo.
Añade el nombre del módulo en la rama (feat/telemetry-batch) para mayor claridad.
go.work soporta bloques replace para anulaciones locales.
Prefiere las rutas use sobre las reemplazos absolutas frágiles.
Usa filtros de ruta y git diff --name-only para seleccionar entradas de la matriz.
Aún ejecuta integraciones periódicas completas del espacio de trabajo en main.
Raramente vale la pena.
Los módulos Go ya versionan las dependencias; los submódulos añaden fricción de VCS.
Indica qué módulo versiona cada etiqueta, la rama por defecto y los comandos de verificación GOWORK=off para los mantenedores.
Versiones 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 - 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: 18 jul 2026