Regras de Módulo e Dependência
Semver, dependências mínimas e limites de pacotes internos.
//
Busque em todas as páginas da documentação
Semver, dependências mínimas e limites de pacotes internos.
Referência rápida para autores de módulos e equipes de plataforma que regem a higiene do go.mod em serviços e bibliotecas.
go.mod, go.sum ou caminhos de importação.cmd/.govulncheck e automação de atualização de dependências.go.work ainda precisam de organização por módulo.| Regra | Comando / Padrão | Sinal de Falha |
|---|---|---|
| Tidy antes de mesclar | go mod tidy | Diff não vazio em go.mod/go.sum |
| Fixar versão do Go | go 1.26 corresponde à imagem de CI | Incompatibilidade local/CI toolchain |
| Um caminho de módulo por raiz de repositório (padrão) | module example.com/foo | Módulos aninhados acidentais sem go.work |
| Exigir replaces intencionais | replace com comentário + issue | replace permanente para forks |
| Retratar tags ruins | diretiva retract em go.mod | Consumidores resolvem pseudo-versões quebradas |
| Vendorizar apenas com política | go mod vendor + política de commit | Desvio surpresa do vendor |
| Regra | Biblioteca | Aplicação / cmd |
|---|---|---|
| Tags git Semver | v1.4.2 obrigatório | Tags internas opcionais |
| Mudança de API que quebra compatibilidade | Bump principal / caminho de módulo v2 | Refatorar livremente dentro do limite de implantação |
| Pré-lançamento | v0.y.z ou internal/ | Branches de recursos |
| Changelog | CHANGELOG.md ou notas de lançamento | Notas de implantação |
| Atualização do consumidor | go get example.com/foo@v1.4.2 | Build da imagem fixa o commit |
| Regra | Fazer | Evitar |
|---|---|---|
| Deps diretas | Apenas o que o pacote importa | Copiar e colar pilhas de go get de posts de blog |
| Consciência indireta | Revisar go mod why -m | Ignorar inchaço transitivo |
| Stdlib primeiro | net/http, encoding/json | Framework pesado para um manipulador |
| Limites de interface | Pequenos adaptadores nas bordas | Importar ORM em pacotes de domínio |
| Deps de teste | require apenas para teste em módulo separado ou tags de build | Importações de produção de testify em código de biblioteca |
| Verificação de licença | Licenças na lista de permissões na política da plataforma | Deps transitivas AGPL não revisadas |
| Regra | Padrão | Aplicação |
|---|---|---|
| internal/ | example.com/foo/internal/bar | Compilador rejeita importadores externos |
| cmd/ | Apenas main fino | Sem lógica de negócios em main |
| Raiz da API pública | Pacotes estáveis na raiz do módulo ou pkg/ (escolha da equipe) | Documentar no README |
| Sem catch-alls de utilitários | Dividir por domínio | Revisar pequenas melhorias no crescimento do pacote util |
| Ciclos de importação | Refatorar via interfaces | Falha go build |
| Importações em branco | Apenas registro de efeito colateral | Comentário explica driver/plugin |
| Regra | Ferramenta | Cadência |
|---|---|---|
| Verificação de vulnerabilidade | govulncheck ./... | Todo PR que toque em deps |
| Integridade do Sum | Commit go.sum | Nunca .gitignore go.sum |
| Módulos privados | GOPRIVATE, .netrc/token | Documentar na integração |
| Exportação de SBOM | Artefato do pipeline de build | Tags de lançamento |
| Fixar versões de linters/ações de CI | SHA ou tags semver | Política de cadeia de suprimentos |
| Regra | Fazer | Evitar |
|---|---|---|
| Replace local | go.work lista módulos | Hacks replace ../ registrados |
| Builds de CI de cada módulo | Matriz ou go work sync | Um módulo verde, outros quebrados |
| Módulos publicáveis | Lançar do diretório do módulo sem replaces apenas de work | Publicar com caminhos locais |
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 // não importável fora do módulo
cmd/
widgetctl/
main.go // main finoCorreções temporárias de fork com link para issue e data de remoção.
Não é um substituto permanente para lançamentos upstream.
Opcional.
Bibliotecas que publicam para go get devem usar tags semver para lançamentos.
O caminho de importação inclui o sufixo /v2; mudanças de comportamento importantes são enviadas para lá.
Execute a partir da raiz do módulo; faça commit do tidy atômico com a importação que o causou.
Investigue se o churn do tidy é constante - frequentemente sinaliza versões flutuantes.
Cada dependência direta precisa de um proprietário e um plano de remoção.
Prefira stdlib e módulos pequenos e focados em vez de mega-frameworks para bibliotecas.
Sim, com GOPRIVATE e versionamento documentado.
Trate-os como consumidores semver externos.
Builds air-gapped, implantações reproduzíveis ou política que exige fontes registradas.
Adiciona custo de manutenção em atualizações.
Marque tags ruins para que go get as evite sem excluir o histórico do git.
Sim, no arquivo de módulo principal; use tags de build para mantê-las fora dos binários de produção.
Algumas equipes dividem a integração em módulos separados.
Use para commits de pré-lançamento; prefira lançamentos taggeados para pins de produção.
Documente em Pseudo-versões, replace e retract.
go mod graph, go mod why -m e análise de alcançabilidade do govulncheck.
Bloqueie merges em CVEs críticos alcançáveis sem plano.
O alvo e o subconjunto de stdlib diferem; mantenha o módulo organizado, mas verifique se as importações compilam na toolchain do dispositivo.
Versões de Stack: 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).
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026