go work: Modo de Workspace para Repositórios Multi-Módulo

go.work permite compilar vários módulos juntos usando código-fonte local em vez de versões publicadas.

É a maneira suportada de desenvolver monorepos multi-módulo sem espalhar diretivas replace temporárias em cada go.mod.

Resumo

O modo de workspace adiciona um arquivo go.work listando diretórios de módulos com diretivas use.

Quando GOWORK aponta para esse arquivo (detectado automaticamente em diretórios pais), a toolchain resolve esses módulos para caminhos locais.

Seus arquivos go.mod individuais permanecem publicáveis; a configuração do workspace é tipicamente local ou commitada apenas para orquestração de desenvolvimento em todo o repositório.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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 .

Quando usar isso:

• Editando módulos de biblioteca e serviço lado a lado em um único clone.
• Evitando linhas replace => ../lib commitadas que quebram em diferentes layouts de máquina.
• Executando CI que compila múltiplos módulos com versões locais consistentes.

Exemplo de Trabalho

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

// lib/greet.go
package lib
 
func Greet() string { return "hello from 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 .

O que isso demonstra:

• app requer example.com/lib sem uma pseudo-versão ou replace em go.mod.
• go.work diz à toolchain para usar ./lib no disco.
• Publicar app sozinho ainda registra um require adequado para consumidores.

Mergulho Profundo

Como Funciona

1. go work init cria go.work na raiz do repositório (ou no caminho escolhido).
2. As entradas use listam as raízes dos módulos relativas ao arquivo de trabalho.
3. Builds dentro dos módulos membros preferem fontes locais para os caminhos listados.
4. GOWORK=off desabilita o modo de workspace para imitar consumidores externos.
5. replace em go.work (não apenas em go.mod) pode substituir versões em todo o workspace.

Os arquivos de workspace não são importados por módulos downstream de suas bibliotecas.

Eles coordenam desenvolvedores e CI de monorepos, não grafos de usuários finais.

go.work vs replace em go.mod

Notas Go

# Adicionar um módulo posteriormente
go work use ./newservice
 
# Sincronizar go line do workspace com os módulos
go work sync
 
# Executar testes em todo o workspace
go work edit -json
go test ./...

// go.work com replace (nível de workspace)
go 1.26
 
use (
    ./app
    ./lib
)
 
replace example.com/legacy => ./legacy

Armadilhas

• Esquecer GOWORK=off em pipelines de release pode ocultar o fato de que código local não publicado é necessário.
• Commitar go.work sem documentar a intenção confunde contribuidores que esperam o modo de módulo puro.
• O Workspace não publica módulos locais transitivos - marque e envie lib antes que usuários externos possam resolver app.
• Múltiplos arquivos go.work - apenas o encontrado ao percorrer os pais se aplica; mantenha um único arquivo raiz quando possível.
• IDEs precisam habilitar suporte a workspace Go - a maioria faz isso quando go.work está presente.

Alternativas

• Monorepo de módulo único - Grafo mais simples; use quando uma linha semver for suficiente.
• replace em go.mod - Rápido para uso único; ruim para equipes compartilhadas sem caminhos padrão.
• Pseudo-versões publicadas - CI publica versões de desenvolvimento a partir de branches de recursos.

FAQs

Relacionados

• Pseudo-Versions, replace & retract Directives - Alternativa ao replace
• go.mod, go.sum & Minimal Version Selection - Grafos por módulo
• Standard Project Layout for Services and Libraries - Layout de Monorepo
• Packages & Modules Basics - Início rápido do Workspace

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build), e golangci-lint (latest - verifique o conjunto de linters na build). 383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x211t3x1v1t1v1z1t20