Pacotes, Módulos e Boas Práticas de Layout de Projeto

Q: Como auditar o inchaço de módulos?

go list -m all, scanners de dependência e go mod tidy periódico após refatorações. Remova primeiro os requires diretos não utilizados.

Convenções de higiene de módulos, marcação e publicação.

Esses hábitos mantêm os grafos de importação pequenos, as releases previsíveis e os monorepos manteníveis à medida que as equipes crescem.

Como Usar Esta Lista

Aplique durante a criação do módulo, antes de marcar v1.0.0 e na revisão de release.
Automatize com go mod tidy, go test ./..., go vet ./... e golangci-lint no CI.
Trate mudanças quebradoras de caminho de importação como eventos semver (/v2 para bibliotecas).
Revise ao adicionar um segundo binário, dividir módulos ou integrar consumidores externos.

A - Identidade e versionamento do módulo

Escolha um caminho de módulo que corresponda ao domínio de hospedagem. Use github.com/org/repo ou seu domínio real para que go get resolva para sempre.
Commite go.mod e go.sum juntos. Builds reproduzíveis e verificação de checksum dependem de ambos os arquivos.
Execute go mod tidy antes de cada merge e tag de release. Órfãos e indiretos ausentes nunca devem surpreender o CI.
Marque releases com semver correspondendo às linhas principais do módulo. Módulos v2+ precisam de /v2 no caminho do módulo e nos caminhos de importação.
Retrate tags ruins em vez de fingir que elas nunca existiram. Documente a migração nas notas de release ao retratar.

B - Dependências e upgrades

Fixe dependências diretas com go get module@version intencional. Evite @latest cegamente em produção principal sem revisão do changelog.
Entenda MVS antes de lutar contra o grafo. Aumente a versão mínima que satisfaz o grafo; não edite manualmente versões transitivas sem motivo.
Use go mod why -m para justificar novos módulos transitivos. Remova peso não utilizado antes que ele se torne enraizado.
Defina GOPRIVATE para módulos privados e desabilite sumdb onde apropriado. Documente a autenticação VCS para CI e laptops.
Prefira go.work em vez de caminhos replace específicos da máquina em branches compartilhados. Overrides locais pertencem a arquivos de workspace ou configuração de desenvolvimento documentada.

C - Design e layout de pacotes

Mantenha cmd/ enxuto; injete a orquestração em main, a lógica em outro lugar. Um pacote main por binário sob cmd/<nome>/.
Coloque detalhes de implementação em internal/. Deixe o compilador impor limites em vez de apenas avisos no README.
Nomeie pacotes pelo que eles fazem, não util ou common. Nomes curtos em minúsculas; evite repetição de importação nos locais de chamada.
Exponha a menor superfície de API que atenda às necessidades do consumidor. Identificadores maiúsculos são promessas de compatibilidade.
Quebre ciclos de importação com pacotes de contrato compartilhados, não com importações de ponto. Interfaces e DTOs vivem abaixo de ambos os lados.

D - Publicação e consumo

Documente quais pacotes são estáveis para importadores externos. README mais pacotes opcionais pkg/ ou de biblioteca de nível superior.
Adicione um arquivo LICENSE compatível com seu proxy de módulo. Consumidores e revisão legal esperam isso na raiz do módulo.
Execute go test ./... e go vet ./... em cada candidato a tag. Consumidores de módulos herdam sua barra de qualidade.
Publique entradas de changelog para mudanças de API e caminho de módulo. Inclua etapas de upgrade para migrações /v2.
Faça vendor apenas com uma política de atualização documentada. go mod vendor ajuda o CI em modo air-gapped; não deixe o vendor apodrecer silenciosamente.

E - Repositórios Monorepo e Multi-módulo

Por padrão, use um módulo até que as linhas de release realmente diverjam. Arquivos go.mod extras adicionam custo operacional.
Commite go.work raiz quando as equipes co-desenvolvem módulos diariamente. Documente verificações GOWORK=off para validação de publicação.
Marque cada módulo independentemente em repositórios multi-módulo. O CI não deve assumir que uma tag Git versiona todos os sub-módulos.
Evite suposições internal/ entre módulos. internal não abrange limites de módulo, mesmo em um único repositório Git.
Divida módulos quando semver, propriedade ou conjuntos de consumidores diferirem. Não quando as pastas apenas parecem lotadas.

FAQs

Quando devo criar um caminho de módulo v2?

Quando você remover ou alterar APIs exportadas de forma incompatível.

Envie example.com/lib/v2 e mantenha v1 no caminho antigo até que a depreciação seja concluída.

Devo commitar diretivas de replace?

Apenas para forks permanentes com acordo da equipe.

Caminhos locais temporários pertencem a go.work ou documentação do desenvolvedor, não a branches principais compartilhadas.

Com que frequência devo marcar releases de biblioteca?

Marque quando os consumidores precisarem de um ponto de upgrade reproduzível.

Tags de patch para correções, minor para recursos compatíveis com versões anteriores.

O pkg/ é necessário para bibliotecas de código aberto?

Não - a clareza é mais importante que o nome da pasta.

Documente os caminhos de importação suportados no README, independentemente do layout.

O que pertence à diretiva go do go.mod?

A toolchain Go mínima que seu módulo requer para recursos de linguagem.

Aumente-a deliberadamente ao adotar novas bibliotecas padrão ou sintaxe.

Aplicativos devem usar versionamento semântico de importação?

Aplicativos são módulos principais; mudanças quebradoras são internas.

Bibliotecas devem disciplina semver e /v2 para importadores downstream.

Como auditar o inchaço de módulos?

go list -m all, scanners de dependência e go mod tidy periódico após refatorações.

Remova primeiro os requires diretos não utilizados.

Quando o vendoring vale a pena?

Builds air-gapped, recuperação de desastres ou trilhas de auditoria estritas de terceiros.

Combine com atualização automática de vendor no CI.

Posso renomear meu caminho de módulo?

Trate como quebra: novo caminho, guia de migração e possivelmente aumento de versão principal.

O caminho antigo pode precisar de um módulo de compatibilidade ou redirecionamento no README.

Quais verificações rodam antes do go publish?

Testes, vet, diff limpo do tidy, tag correta no commit e LICENSE presente.

A ingestão do proxy é eventual; verifique com go list -m -versions após o push da tag.

Relacionados

Pacotes e Módulos: A Unidade de Distribuição do Go - Visão geral conceitual
go.mod, go.sum e Seleção Mínima de Versão - Arquivos e MVS
Layout Padrão de Projeto para Serviços e Bibliotecas - cmd, internal, pkg
Noções Básicas de Pacotes e Módulos - Pontos de partida executáveis

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizadores - 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).

Pacotes, Módulos e Boas Práticas de Layout de Projeto

Convenções de higiene de módulos, marcação e publicação.

Esses hábitos mantêm os grafos de importação pequenos, as releases previsíveis e os monorepos manteníveis à medida que as equipes crescem.

Como Usar Esta Lista

Aplique durante a criação do módulo, antes de marcar v1.0.0 e na revisão de release.
Automatize com go mod tidy, go test ./..., go vet ./... e golangci-lint no CI.
Trate mudanças quebradoras de caminho de importação como eventos semver (/v2 para bibliotecas).
Revise ao adicionar um segundo binário, dividir módulos ou integrar consumidores externos.

A - Identidade e versionamento do módulo

Escolha um caminho de módulo que corresponda ao domínio de hospedagem. Use github.com/org/repo ou seu domínio real para que go get resolva para sempre.
Commite go.mod e go.sum juntos. Builds reproduzíveis e verificação de checksum dependem de ambos os arquivos.
Execute go mod tidy antes de cada merge e tag de release. Órfãos e indiretos ausentes nunca devem surpreender o CI.
Marque releases com semver correspondendo às linhas principais do módulo. Módulos v2+ precisam de /v2 no caminho do módulo e nos caminhos de importação.
Retrate tags ruins em vez de fingir que elas nunca existiram. Documente a migração nas notas de release ao retratar.

B - Dependências e upgrades

Fixe dependências diretas com go get module@version intencional. Evite @latest cegamente em produção principal sem revisão do changelog.
Entenda MVS antes de lutar contra o grafo. Aumente a versão mínima que satisfaz o grafo; não edite manualmente versões transitivas sem motivo.
Use go mod why -m para justificar novos módulos transitivos. Remova peso não utilizado antes que ele se torne enraizado.
Defina GOPRIVATE para módulos privados e desabilite sumdb onde apropriado. Documente a autenticação VCS para CI e laptops.
Prefira go.work em vez de caminhos replace específicos da máquina em branches compartilhados. Overrides locais pertencem a arquivos de workspace ou configuração de desenvolvimento documentada.

C - Design e layout de pacotes

Mantenha cmd/ enxuto; injete a orquestração em main, a lógica em outro lugar. Um pacote main por binário sob cmd/<nome>/.
Coloque detalhes de implementação em internal/. Deixe o compilador impor limites em vez de apenas avisos no README.
Nomeie pacotes pelo que eles fazem, não util ou common. Nomes curtos em minúsculas; evite repetição de importação nos locais de chamada.
Exponha a menor superfície de API que atenda às necessidades do consumidor. Identificadores maiúsculos são promessas de compatibilidade.
Quebre ciclos de importação com pacotes de contrato compartilhados, não com importações de ponto. Interfaces e DTOs vivem abaixo de ambos os lados.

D - Publicação e consumo

Documente quais pacotes são estáveis para importadores externos. README mais pacotes opcionais pkg/ ou de biblioteca de nível superior.
Adicione um arquivo LICENSE compatível com seu proxy de módulo. Consumidores e revisão legal esperam isso na raiz do módulo.
Execute go test ./... e go vet ./... em cada candidato a tag. Consumidores de módulos herdam sua barra de qualidade.
Publique entradas de changelog para mudanças de API e caminho de módulo. Inclua etapas de upgrade para migrações /v2.
Faça vendor apenas com uma política de atualização documentada. go mod vendor ajuda o CI em modo air-gapped; não deixe o vendor apodrecer silenciosamente.

E - Repositórios Monorepo e Multi-módulo

Por padrão, use um módulo até que as linhas de release realmente diverjam. Arquivos go.mod extras adicionam custo operacional.
Commite go.work raiz quando as equipes co-desenvolvem módulos diariamente. Documente verificações GOWORK=off para validação de publicação.
Marque cada módulo independentemente em repositórios multi-módulo. O CI não deve assumir que uma tag Git versiona todos os sub-módulos.
Evite suposições internal/ entre módulos. internal não abrange limites de módulo, mesmo em um único repositório Git.
Divida módulos quando semver, propriedade ou conjuntos de consumidores diferirem. Não quando as pastas apenas parecem lotadas.

FAQs

Quando devo criar um caminho de módulo v2?

Quando você remover ou alterar APIs exportadas de forma incompatível.

Envie example.com/lib/v2 e mantenha v1 no caminho antigo até que a depreciação seja concluída.

Devo commitar diretivas de replace?

Apenas para forks permanentes com acordo da equipe.

Caminhos locais temporários pertencem a go.work ou documentação do desenvolvedor, não a branches principais compartilhadas.

Com que frequência devo marcar releases de biblioteca?

Marque quando os consumidores precisarem de um ponto de upgrade reproduzível.

Tags de patch para correções, minor para recursos compatíveis com versões anteriores.

O pkg/ é necessário para bibliotecas de código aberto?

Não - a clareza é mais importante que o nome da pasta.

Documente os caminhos de importação suportados no README, independentemente do layout.

O que pertence à diretiva go do go.mod?

A toolchain Go mínima que seu módulo requer para recursos de linguagem.

Aumente-a deliberadamente ao adotar novas bibliotecas padrão ou sintaxe.

Aplicativos devem usar versionamento semântico de importação?

Aplicativos são módulos principais; mudanças quebradoras são internas.

Bibliotecas devem disciplina semver e /v2 para importadores downstream.

Como auditar o inchaço de módulos?

go list -m all, scanners de dependência e go mod tidy periódico após refatorações.

Remova primeiro os requires diretos não utilizados.

Quando o vendoring vale a pena?

Builds air-gapped, recuperação de desastres ou trilhas de auditoria estritas de terceiros.

Combine com atualização automática de vendor no CI.

Posso renomear meu caminho de módulo?

Trate como quebra: novo caminho, guia de migração e possivelmente aumento de versão principal.

O caminho antigo pode precisar de um módulo de compatibilidade ou redirecionamento no README.

Quais verificações rodam antes do go publish?

Testes, vet, diff limpo do tidy, tag correta no commit e LICENSE presente.

A ingestão do proxy é eventual; verifique com go list -m -versions após o push da tag.

Relacionados

Pacotes e Módulos: A Unidade de Distribuição do Go - Visão geral conceitual
go.mod, go.sum e Seleção Mínima de Versão - Arquivos e MVS
Layout Padrão de Projeto para Serviços e Bibliotecas - cmd, internal, pkg
Noções Básicas de Pacotes e Módulos - Pontos de partida executáveis

Versões da Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizadores - 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).

Pacotes, Módulos e Boas Práticas de Layout de Projeto

Buscar na documentação

Pacotes, Módulos e Boas Práticas de Layout de Projeto