go work: Modo de Espacio de Trabajo para Repositorios Multi-Módulo

go.work te permite compilar varios módulos juntos usando código fuente local en lugar de versiones publicadas.

Es la forma soportada de desarrollar monorepos multi-módulo sin esparcir directivas replace temporales en cada go.mod.

Resumen

El modo de espacio de trabajo añade un archivo go.work que lista directorios de módulos con directivas use.

Cuando GOWORK apunta a ese archivo (detectado automáticamente en directorios padre), la cadena de herramientas resuelve esos módulos a rutas locales.

Tus archivos go.mod individuales siguen siendo publicables; la configuración del espacio de trabajo es típicamente local o se confirma solo para la orquestación de desarrollo a nivel de repositorio.

Receta

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

mkdir -p repo/{app,lib}
cd repo/lib && go mod init example.com/lib
cd ../app && go mod init example.com/app
cd ..
go work init ./app ./lib
go work use ./app ./lib

cd app
go run .

Cuándo usar esto:

• Editar módulos de biblioteca y servicio uno al lado del otro en una sola clonación.
• Evitar líneas replace => ../lib confirmadas que fallan en diferentes diseños de máquina.
• Ejecutar CI que compila múltiples módulos con versiones locales consistentes.

Ejemplo de Trabajo

repo/
  go.work
  app/
    go.mod
    main.go
  lib/
    go.mod
    greet.go

// lib/greet.go
package lib
 
func Greet() string { return "hola desde lib" }

// lib/go.mod
module example.com/lib
 
go 1.26

// app/go.mod
module example.com/app
 
go 1.26
 
require example.com/lib v0.0.0

// app/main.go
package main
 
import (
    "fmt"
    "example.com/lib"
)
 
func main() {
    fmt.Println(lib.Greet())
}

// go.work
go 1.26
 
use (
    ./app
    ./lib
)

cd app
go run .

Lo que esto demuestra:

• app requiere example.com/lib sin una pseudo-versión o replace en go.mod.
• go.work le dice a la cadena de herramientas que use ./lib en el disco.
• Publicar app solo todavía registra un require adecuado para los consumidores.

Inmersión Profunda

Cómo Funciona

1. go work init crea go.work en la raíz del repositorio (o en la ruta elegida).
2. Las entradas use listan las raíces de los módulos relativas al archivo de trabajo.
3. Las compilaciones dentro de los módulos miembros prefieren fuentes locales para las rutas listadas.
4. GOWORK=off deshabilita el modo de espacio de trabajo para imitar a los consumidores externos.
5. replace en go.work (no solo en go.mod) puede anular versiones en todo el espacio de trabajo.

Los archivos de espacio de trabajo no son importados por módulos descendientes de tus bibliotecas.

Coordinan a los desarrolladores y la CI del monorepo, no los grafos de usuarios finales.

go.work vs replace en go.mod

Notas de Go

# Añadir un módulo más tarde
go work use ./newservice
 
# Sincronizar la línea go del espacio de trabajo con los módulos
go work sync
 
# Ejecutar pruebas en todo el espacio de trabajo
go work edit -json
go test ./...

// go.work con replace (a nivel de espacio de trabajo)
go 1.26
 
use (
    ./app
    ./lib
)
 
replace example.com/legacy => ./legacy

Trampas

• Olvidar GOWORK=off en los pipelines de lanzamiento puede ocultar el hecho de que se requiere código local no publicado.
• Confirmar go.work sin documentar la intención confunde a los colaboradores que esperan el modo de módulo puro.
• El espacio de trabajo no publica módulos locales transitivos - etiqueta y envía lib antes de que los usuarios externos puedan resolver app.
• Múltiples archivos go.work - solo el que se encuentra al recorrer los padres se aplica; mantén un solo archivo raíz cuando sea posible.
• Los IDE deben habilitar el soporte para espacios de trabajo de Go - la mayoría lo hacen cuando go.work está presente.

Alternativas

• Monorepo de un solo módulo - Grafo más simple; usar cuando una línea semver es suficiente.
• replace en go.mod - Rápido para un solo uso; pobre para equipos compartidos sin rutas estándar.
• Pseudo-versiones publicadas - La CI publica versiones de desarrollo desde ramas de características.

Preguntas Frecuentes

Relacionado

• Pseudo-Versiones, Directivas replace y retract - Alternativa a replace
• go.mod, go.sum y Selección Mínima de Versiones - Grafos por módulo
• Diseño de Proyecto Estándar para Servicios y Bibliotecas - Diseño de Monorepo
• Conceptos Básicos de Paquetes y Módulos - Inicio rápido del espacio de trabajo

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, 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). 383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x211t3x1v1t1v1z1t20