Padrões Git de Monorepo com go work

Q: Como os consumidores importam módulos de monorepo?

Por caminho do módulo em cada go.mod, não pela raiz do repositório. go get github.com/acme/telemetry@v0.4.0 busca apenas essa subárvore de módulo.

Q: Um PR pode atualizar dois módulos?

Sim. Execute testes com o workspace ativado e GOWORK=off para cada módulo afetado antes de mesclar.

Q: Como lidar com versões principais divergentes?

Caminhos de módulo separados (/v2) e tags por versão principal. O workspace pode incluir ambas as linhas durante a migração.

Q: go.work substitui go.mod require?

Não. Ele substitui a resolução localmente; go.mod ainda lista os semver requires pretendidos para os consumidores.

Q: Workspaces podem incluir diretivas replace?

go.work suporta blocos replace para substituições locais. Prefira caminhos use em vez de replaces absolutos frágeis.

Q: Como testar apenas módulos alterados em CI?

Use filtros de caminho e git diff --name-only para selecionar entradas da matriz. Ainda execute integrações completas periódicas do workspace em main.

Um único repositório Git pode hospedar múltiplos módulos Go coordenados por go.work durante o desenvolvimento.

O histórico do Git permanece unificado enquanto cada módulo mantém seu próprio go.mod, tags e grafo de consumidores.

Resumo

Monorepos são adequados para equipes de plataforma que enviam bibliotecas e serviços compartilhados juntos.

Use go.work localmente para substituir diretivas replace entre módulos em arquivos go.mod commitados.

Marque e faça CI de cada módulo explicitamente para que proxies e consumidores resolvam as versões corretas.

Receita

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

# Layout do repositório
# services/api/go.mod
# libs/auth/go.mod
 
cd repo-root
go work init ./services/api ./libs/auth
go work use -r .   # opcional: descobrir módulos
 
# Desenvolver entre módulos
cd services/api
go test ./...
 
# Validar visualização de publicação (sem workspace)
GOWORK=off go test ./...

Quando usar isso:

Alterações atômicas de API entre uma biblioteca e seu serviço consumidor em um único PR.
Substituição de caminhos replace específicos da máquina em branches compartilhados.
Padronização de CI e tagging multi-módulo em um único repositório Git.
Onboarding de desenvolvedores que não devem editar as linhas de replace go.mod uns dos outros.

Exemplo de Trabalho

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
)

# Alterar a API de telemetria e corrigir o faturamento em um único branch
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: adicionar exportação em lote; billing: adotar API em lote"
git push -u origin feat/telemetry-batch

Marque apenas o módulo da biblioteca ao lançar 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.0

O que isso demonstra:

go.work conecta implicitamente os replaces locais durante o desenvolvimento.
GOWORK=off simula o que os consumidores de módulos experimentam.
Nomes de tags Git versionam o lançamento do módulo de telemetria independentemente.

Aprofundamento

Como Funciona

Cada módulo tem seu próprio go.mod na raiz de um subdiretório.
go.work na raiz do repositório lista os diretórios dos módulos nas diretivas use.
O comando Go prefere módulos do workspace em vez de versões de proxy para esses caminhos.
Git rastreia um único histórico; merges podem tocar múltiplos arquivos go.mod em um único PR.
Tags de lançamento podem ter como alvo commits específicos de subdiretórios com convenção documentada.

go.work.sum registra checksums para resolução de workspace, semelhante a go.sum.

Commite go.work quando toda a equipe compartilha o layout do workspace.

Mantenha experimentos pessoais em go.work não rastreado ou substituição de ambiente GOWORK.

Padrões Git

Padrão	Propósito
Rótulos de PR com escopo de caminho	Mostrar quais módulos um PR afeta
CODEOWNERS por módulo	Roteia a revisão para a equipe proprietária
Prefixo de tag `telemetry/v0.4.0`	Desambigua tags multi-módulo (documentar no README)
Matriz de CI por `go.mod`	Feedback mais rápido em repositórios grandes
`GOWORK=off` job de release	Verifica o grafo de módulos publicáveis

go.work vs replace

Mecanismo	Commitedo para main compartilhado?	Impacto no consumidor
`go.work`	Auxílio de desenvolvimento opcional para toda a equipe	Nenhum (não publicado)
`replace` em `go.mod`	Evitar para caminhos locais	Quebra `go get` para usuários externos
require versionado	Sim	Caminho normal do consumidor

Esboço de CI de Monorepo

strategy:
  matrix:
    module: [libs/telemetry, services/billing]
steps:
  - run: cd ${{ matrix.module }} && GOWORK=off go test ./...

O job de workspace raiz ainda pode executar go test ./... de go.work para confiança na integração.

Armadilhas

Caminhos replace ../libs commitados - Quebram clones externos. Correção: go.work para desenvolvimento local; exigir versões semver em main.
Tag única para módulos não relacionados - Consumidores não podem fixar um módulo sem puxar outros. Correção: tags independentes ou prefixos documentados.
Assumir que internal/ abrange módulos - O compilador impõe por raiz de módulo. Correção: código compartilhado em pacotes publicados ou um único módulo até que a divisão seja real.
Esquecer GOWORK=off em CI de release - Envia surpresas do grafo apenas do workspace. Correção: modo off obrigatório antes da tag.
PRs enormes entre módulos - Paralisia de revisão. Correção: empilhar PRs ou propriedade estrita de módulo com fatias menores.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Módulo único	Uma linha de release, grafo simples	Semver independente por subsistema
Multi-repo	Limites rígidos de equipe	Mudanças atômicas frequentes entre cortes
Bazel / build customizado	Orquestração poliglota não-Go	Fluxos de trabalho `go` command padrão são suficientes
Submódulos Git	Separação legada	Ergonomia de módulos Go preferida

FAQs

go.work deve ser commitado?

Sim, quando todos os desenvolvedores usam o mesmo conjunto de módulos diariamente.

Não, quando é um superconjunto pessoal de módulos; use um arquivo local não rastreado em vez disso.

Como os consumidores importam módulos de monorepo?

Por caminho do módulo em cada go.mod, não pela raiz do repositório.

go get github.com/acme/telemetry@v0.4.0 busca apenas essa subárvore de módulo.

Um PR pode atualizar dois módulos?

Sim.

Execute testes com o workspace ativado e GOWORK=off para cada módulo afetado antes de mesclar.

Como lidar com versões principais divergentes?

Caminhos de módulo separados (/v2) e tags por versão principal.

O workspace pode incluir ambas as linhas durante a migração.

go.work substitui go.mod require?

Não.

Ele substitui a resolução localmente; go.mod ainda lista os semver requires pretendidos para os consumidores.

Como dividir um módulo de monorepo?

Extraia o histórico com filter-repo ou copie a subárvore, publique o novo caminho do módulo, retifique os caminhos antigos se necessário.

Planeje a migração do caminho de importação no changelog.

E os diretórios vendor por módulo?

Possível em cada raiz de módulo.

Atualize o vendor no PR que atualiza apenas as dependências desse módulo.

Como funciona a nomenclatura de branches?

Os mesmos padrões de trunk de repositórios de módulo único.

Adicione o nome do módulo no branch (feat/telemetry-batch) para clareza.

Workspaces podem incluir diretivas replace?

go.work suporta blocos replace para substituições locais.

Prefira caminhos use em vez de replaces absolutos frágeis.

Como testar apenas módulos alterados em CI?

Use filtros de caminho e git diff --name-only para selecionar entradas da matriz.

Ainda execute integrações completas periódicas do workspace em main.

Workspaces podem ser misturados com submódulos git?

Raramente vale a pena.

Módulos Go já versionam dependências; submódulos adicionam atrito de VCS.

Como documentar o tagging no README?

Declare qual módulo cada tag versiona, o branch padrão e os comandos de verificação GOWORK=off para mantenedores.

Relacionados

go work: Modo Workspace para Repositórios Multi-Módulo - Mecânicas do workspace em profundidade
Git para Equipes Go - Visão geral do Git mais lançamento de módulos
GitHub Actions para Repositórios Go - CI de matriz para múltiplos módulos
Tags Assinadas e Lançamentos de Módulos Go - Tagging por módulo
Rebasing, Cherry-Pick & Worktrees - Checkouts paralelos em repositórios grandes

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

O histórico do Git permanece unificado enquanto cada módulo mantém seu próprio go.mod, tags e grafo de consumidores.

Resumo

Monorepos são adequados para equipes de plataforma que enviam bibliotecas e serviços compartilhados juntos.

Use go.work localmente para substituir diretivas replace entre módulos em arquivos go.mod commitados.

Marque e faça CI de cada módulo explicitamente para que proxies e consumidores resolvam as versões corretas.

Receita

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

# Layout do repositório
# services/api/go.mod
# libs/auth/go.mod
 
cd repo-root
go work init ./services/api ./libs/auth
go work use -r .   # opcional: descobrir módulos
 
# Desenvolver entre módulos
cd services/api
go test ./...
 
# Validar visualização de publicação (sem workspace)
GOWORK=off go test ./...

Quando usar isso:

Alterações atômicas de API entre uma biblioteca e seu serviço consumidor em um único PR.
Substituição de caminhos replace específicos da máquina em branches compartilhados.
Padronização de CI e tagging multi-módulo em um único repositório Git.
Onboarding de desenvolvedores que não devem editar as linhas de replace go.mod uns dos outros.

Exemplo de Trabalho

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
)

# Alterar a API de telemetria e corrigir o faturamento em um único branch
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: adicionar exportação em lote; billing: adotar API em lote"
git push -u origin feat/telemetry-batch

Marque apenas o módulo da biblioteca ao lançar 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.0

O que isso demonstra:

go.work conecta implicitamente os replaces locais durante o desenvolvimento.
GOWORK=off simula o que os consumidores de módulos experimentam.
Nomes de tags Git versionam o lançamento do módulo de telemetria independentemente.

Aprofundamento

Como Funciona

Cada módulo tem seu próprio go.mod na raiz de um subdiretório.
go.work na raiz do repositório lista os diretórios dos módulos nas diretivas use.
O comando Go prefere módulos do workspace em vez de versões de proxy para esses caminhos.
Git rastreia um único histórico; merges podem tocar múltiplos arquivos go.mod em um único PR.
Tags de lançamento podem ter como alvo commits específicos de subdiretórios com convenção documentada.

go.work.sum registra checksums para resolução de workspace, semelhante a go.sum.

Commite go.work quando toda a equipe compartilha o layout do workspace.

Mantenha experimentos pessoais em go.work não rastreado ou substituição de ambiente GOWORK.

Padrões Git

Padrão	Propósito
Rótulos de PR com escopo de caminho	Mostrar quais módulos um PR afeta
CODEOWNERS por módulo	Roteia a revisão para a equipe proprietária
Prefixo de tag `telemetry/v0.4.0`	Desambigua tags multi-módulo (documentar no README)
Matriz de CI por `go.mod`	Feedback mais rápido em repositórios grandes
`GOWORK=off` job de release	Verifica o grafo de módulos publicáveis

go.work vs replace

Mecanismo	Commitedo para main compartilhado?	Impacto no consumidor
`go.work`	Auxílio de desenvolvimento opcional para toda a equipe	Nenhum (não publicado)
`replace` em `go.mod`	Evitar para caminhos locais	Quebra `go get` para usuários externos
require versionado	Sim	Caminho normal do consumidor

Esboço de CI de Monorepo

strategy:
  matrix:
    module: [libs/telemetry, services/billing]
steps:
  - run: cd ${{ matrix.module }} && GOWORK=off go test ./...

O job de workspace raiz ainda pode executar go test ./... de go.work para confiança na integração.

Armadilhas

Caminhos replace ../libs commitados - Quebram clones externos. Correção: go.work para desenvolvimento local; exigir versões semver em main.
Tag única para módulos não relacionados - Consumidores não podem fixar um módulo sem puxar outros. Correção: tags independentes ou prefixos documentados.
Assumir que internal/ abrange módulos - O compilador impõe por raiz de módulo. Correção: código compartilhado em pacotes publicados ou um único módulo até que a divisão seja real.
Esquecer GOWORK=off em CI de release - Envia surpresas do grafo apenas do workspace. Correção: modo off obrigatório antes da tag.
PRs enormes entre módulos - Paralisia de revisão. Correção: empilhar PRs ou propriedade estrita de módulo com fatias menores.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Módulo único	Uma linha de release, grafo simples	Semver independente por subsistema
Multi-repo	Limites rígidos de equipe	Mudanças atômicas frequentes entre cortes
Bazel / build customizado	Orquestração poliglota não-Go	Fluxos de trabalho `go` command padrão são suficientes
Submódulos Git	Separação legada	Ergonomia de módulos Go preferida

FAQs

go.work deve ser commitado?

Sim, quando todos os desenvolvedores usam o mesmo conjunto de módulos diariamente.

Não, quando é um superconjunto pessoal de módulos; use um arquivo local não rastreado em vez disso.

Como os consumidores importam módulos de monorepo?

Por caminho do módulo em cada go.mod, não pela raiz do repositório.

go get github.com/acme/telemetry@v0.4.0 busca apenas essa subárvore de módulo.

Um PR pode atualizar dois módulos?

Sim.

Execute testes com o workspace ativado e GOWORK=off para cada módulo afetado antes de mesclar.

Como lidar com versões principais divergentes?

Caminhos de módulo separados (/v2) e tags por versão principal.

O workspace pode incluir ambas as linhas durante a migração.

go.work substitui go.mod require?

Não.

Ele substitui a resolução localmente; go.mod ainda lista os semver requires pretendidos para os consumidores.

Como dividir um módulo de monorepo?

Extraia o histórico com filter-repo ou copie a subárvore, publique o novo caminho do módulo, retifique os caminhos antigos se necessário.

Planeje a migração do caminho de importação no changelog.

E os diretórios vendor por módulo?

Possível em cada raiz de módulo.

Atualize o vendor no PR que atualiza apenas as dependências desse módulo.

Como funciona a nomenclatura de branches?

Os mesmos padrões de trunk de repositórios de módulo único.

Adicione o nome do módulo no branch (feat/telemetry-batch) para clareza.

Workspaces podem incluir diretivas replace?

go.work suporta blocos replace para substituições locais.

Prefira caminhos use em vez de replaces absolutos frágeis.

Como testar apenas módulos alterados em CI?

Use filtros de caminho e git diff --name-only para selecionar entradas da matriz.

Ainda execute integrações completas periódicas do workspace em main.

Workspaces podem ser misturados com submódulos git?

Raramente vale a pena.

Módulos Go já versionam dependências; submódulos adicionam atrito de VCS.

Como documentar o tagging no README?

Declare qual módulo cada tag versiona, o branch padrão e os comandos de verificação GOWORK=off para mantenedores.

Relacionados

go work: Modo Workspace para Repositórios Multi-Módulo - Mecânicas do workspace em profundidade
Git para Equipes Go - Visão geral do Git mais lançamento de módulos
GitHub Actions para Repositórios Go - CI de matriz para múltiplos módulos
Tags Assinadas e Lançamentos de Módulos Go - Tagging por módulo
Rebasing, Cherry-Pick & Worktrees - Checkouts paralelos em repositórios grandes

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

Padrões Git de Monorepo com go work

Buscar na documentação

Padrões Git de Monorepo com go work