Resumo dos Destaques de Pacotes e Módulos

Cada item de destaque das 9 páginas desta seção, reunido em uma única página e agrupado pela página de origem.

Pacotes e Módulos: A Unidade de Distribuição do Go

• Pacotes compilam código; módulos o distribuem e versionam
• Caminhos de importação combinam seu caminho de módulo com a estrutura de diretórios
• Requer sufixos v2+ em caminhos de módulo para alterações que quebram a compatibilidade
• A seleção de versão mínima escolhe as versões mais baixas que atendem a todas as restrições
• Checksums em go.sum evitam ataques de proxy durante downloads de módulos
• Pacotes internos permanecem privados dentro da árvore de módulos

Noções Básicas de Pacotes e Módulos

• O caminho do módulo deve corresponder ao local de hospedagem; go.mod é a raiz versionada da árvore de diretórios
• Apenas nomes capitalizados são exportados para fora de um pacote; nomes em minúsculas permanecem privados do pacote
• go get atualiza go.mod e go.sum; fixe versões com @v1.6.0 em vez de @latest
• Execute go mod tidy após refatorações para manter go.sum alinhado com as importações reais
• Use o diretório internal/ para bloquear importações de fora do módulo inteiramente
• Importações em branco executam funções init sem exigir o uso direto de símbolos

Nomenclatura de Pacotes e Diretórios internal/

• Use nomes de pacotes em minúsculas sem sublinhados para corresponder ao estilo Go e à ergonomia de importação
• Evite nomes como util, common, misc - use nomes descritivos que indiquem o que o pacote faz
• Coloque cada pacote em seu próprio diretório para manter o grafo de compilação e os testes previsíveis
• Restrinja pacotes internos com o diretório internal/ imposto pelo compilador na árvore de módulos
• Módulos externos não podem importar subpacotes internal/, apenas pacotes públicos de nível superior
• Use internal/ para implementação privada, pkg/ apenas para convenção de API pública

go.mod, go.sum e Seleção de Versão Mínima

• MVS seleciona a versão mínima que satisfaz todos os requisitos de módulo no seu grafo de dependência
• go.sum bloqueia o conteúdo e os checksums de módulos para cada versão de dependência para verificar a integridade
• Lembre-se que dependências indiretas recebem comentários // indirect quando não são importadas diretamente
• Nunca edite go.mod manualmente sem executar go mod tidy para evitar requires órfãos
• Use go mod tidy para limpar dependências indiretas e manter go.sum sincronizado com go.mod
• Commite go.sum em seu repositório para que a CI possa verificar se as dependências não foram adulteradas

Pseudo-Versões, replace e retract Diretivas

• Pseudo-versões fixam commits sem tag por timestamp e hash para resolução de dependência
• replace reescreve fontes de módulos sem modificar caminhos de importação em seu código
• retract marca versões como inseguras, mas não as remove do proxy
• Diretivas replace do módulo principal afetam apenas sua compilação, não os consumidores
• Caminhos replace específicos da máquina em branches compartilhados quebram clones em outras máquinas
• Marque lançamentos quando estiverem estáveis em vez de usar pseudo-versões para transparência

Ciclos de Importação, Importações em Branco e Importações de Ponto

• Go proíbe ciclos de importação em tempo de compilação porque a ordem de inicialização seria indefinida
• Importações em branco executam a inicialização do pacote para registro de driver e formato
• Evite importações de ponto em código de produção porque elas ocultam o contexto do pacote
• Extraia interfaces ou DTOs para um terceiro pacote para quebrar ciclos de importação
• Interfaces em pacotes de implementação convidam ciclos se os consumidores precisarem de tipos
• Inicialização pesada em importações em branco retarda a inicialização e oculta falhas em tempo de execução

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

• go.work elimina diretivas replace dispersas no desenvolvimento de monorepos multi-módulo
• GOWORK=off em pipelines de lançamento testa se o código requer módulos locais não publicados
• go.work coordena fluxos de trabalho de desenvolvedores e CI de monorepos, não grafos de dependência de usuários finais
• Diretivas replace do workspace se aplicam a todos os módulos listados em desenvolvimento
• Arquivos go.mod individuais permanecem publicáveis mesmo quando agrupados em um workspace
• Marque e envie bibliotecas antes que consumidores externos possam resolver aplicativos coordenados pelo workspace

Layout Padrão de Projeto para Serviços e Bibliotecas

• Um pacote principal por comando, colocado em cmd/<nome>/
• Use internal/ para bloquear importações de módulos externos em tempo de compilação
• Use pkg/ para APIs públicas, mas reforce a compatibilidade semver
• Extraia a lógica de negócios do main para uma função run()
• pkg/ é apenas uma convenção, semver torna a estabilidade real
• Não bloqueie tudo em internal/ ou os testes entre módulos falharão

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

• Corresponda o caminho do módulo ao domínio de hospedagem para que go get resolva para sempre
• Commite go.mod e go.sum juntos para compilações reproduzíveis
• Execute go mod tidy antes de mesclar e lançar para evitar surpresas na CI
• Marque lançamentos com semver; módulos v2+ exigem /v2 nos caminhos
• Fixe dependências diretas intencionalmente; revise o changelog antes de usar @latest
• Justifique dependências transitivas com go mod why -m antes de adicionar