Pacotes e Módulos: A Unidade de Distribuição do Go
O Go distribui software como módulos versionados, compostos por pacotes.
//
Busque em todas as páginas da documentação
O Go distribui software como módulos versionados, compostos por pacotes.
Essa combinação substituiu o antigo layout GOPATH e oferece builds reproduzíveis, atualizações cientes de semver e uma única história de caminho de importação do seu laptop para a produção.
go.mod.go.mod, go.sum, Seleção Mínima de Versão (MVS), internal/, versionamento semântico de importação.go get selecionou uma versão específica./v2 sufixo); o compartilhamento granular ainda ocorre no nível do pacote, não por arquivo.replace/retract e o grafo de build do comando go.Todo arquivo .go declara package nome e pertence a exatamente um pacote em um diretório.
O caminho de importação é como outro código se refere a esse pacote.
Para código dentro do seu módulo, o caminho de importação é o seu caminho de módulo mais o caminho do diretório sob a raiz do módulo.
Por exemplo, o módulo example.com/widget com o arquivo internal/api/handler.go é importado como example.com/widget/internal/api.
Um módulo é uma árvore de pacotes com raiz em um diretório que contém go.mod.
Esse arquivo nomeia o módulo (module example.com/widget), declara a versão mínima do Go e lista as versões de dependência necessárias.
Os consumidores registram seu módulo em seu go.mod com uma tag semver (ou pseudo-versão) e a toolchain o baixa para o cache de módulos.
Pacotes tratam de compilação e visibilidade (identificadores exportados, regras de internal/).
Módulos tratam de distribuição e versionamento (tags, MVS, checksums).
Analogia: pacotes são cômodos em um prédio; o módulo é o endereço e os termos do contrato de locação para todo o prédio.
Quando você import "github.com/foo/bar/baz", o compilador carrega o pacote baz do módulo github.com/foo/bar na versão selecionada por MVS em seu go.mod.
O versionamento semântico de importação exige que módulos principais v2+ incluam o sufixo principal no caminho do módulo (example.com/lib/v2), para que alterações que quebram a compatibilidade não sejam atualizadas silenciosamente sob a mesma string de importação.
A lista de build é o conjunto de versões de módulo que o comando go usa para um build.
MVS escolhe a versão mínima de cada módulo que ainda satisfaz cada require no grafo.
Isso tende a escolher atualizações conservadoras e mantém os builds previsíveis em diferentes máquinas.
go.sum armazena hashes criptográficos do conteúdo do módulo.
A toolchain verifica os downloads em relação a essas linhas para que um proxy comprometido não possa substituir código silenciosamente.
// go.mod (raiz do módulo)
module example.com/myapp
go 1.26
require (
github.com/google/uuid v1.6.0
golang.org/x/sync v0.10.0
)A diretiva go é um limite mínimo de linguagem/toolchain, não uma dependência de tempo de execução.
Pacotes sob internal/ só podem ser importados por código dentro da árvore pai, o que permite refatorar APIs privadas sem quebrar chamadores externos.
Monorepos frequentemente hospedam um módulo ou muitos.
Um único módulo mantém um go.mod e versionamento compartilhado; múltiplos módulos permitem que equipes marquem e lancem subsistemas independentemente, ao custo de mais arquivos go.mod e fiação replace/workspace entre módulos.
Bibliotecas publicadas para reutilização ampla devem manter caminhos de módulo estáveis, marcar lançamentos e documentar caminhos de migração /v2.
Repositórios de aplicativos podem usar replace localmente ou go.work durante o desenvolvimento sem publicar essas substituições.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Módulo único | Uma linha de versão, CI simples | Grafos grandes, lançamentos acoplados | Aplicativos e bibliotecas pequenas |
| Monorepo multi-módulo | Tags independentes por área | Mais manutenção de go.mod | Equipes de plataforma, infraestrutura compartilhada |
Workspace (go.work) | Edições locais entre módulos sem replace | Não para consumidores publicados | Desenvolvimento multi-módulo ativo |
| Diretório Vendor | Builds offline ou com air-gap | Atualização manual, inchaço do repositório | Builds regulamentados ou offline |
A publicação flui através de tags de controle de versão que correspondem a go list -m -versions.
Pseudo-versões preenchem a lacuna quando você depende de commits sem tag.
Retract marca tags ruins sem excluir o histórico, afastando novas resoluções de lançamentos quebrados.
package main e alguns casos da stdlib diferem; o caminho de importação é autoritário para o compilador.Um pacote é compilado em conjunto a partir de um ou mais arquivos .go em um diretório.
Um módulo é a unidade versionada definida por go.mod que contém esses pacotes e declara dependências.
Fontes e zips de módulos vão para o cache de módulos, tipicamente em $GOPATH/pkg/mod.
O código-fonte do seu projeto permanece no seu repositório; o cache é somente leitura da perspectiva da toolchain.
O versionamento semântico de importação mantém APIs incompatíveis em caminhos de importação distintos para que o código existente continue compilando até que opte por /v2.
Sim, para aplicativos e bibliotecas.
Ele fixa checksums para que CI e colegas de equipe verifiquem o mesmo conteúdo do módulo.
Não - um pacote por diretório (exceto pacotes de teste como package foo_test).
Divida pacotes por subdiretório.
Ela constrói o grafo de requisitos de todos os go.mod envolvidos e aplica a Seleção Mínima de Versão para escolher o semver mais antigo que ainda satisfaz todas as arestas.
O caminho do módulo é o prefixo em go.mod.
O caminho de importação adiciona subdiretórios e pode incluir um sufixo de versão principal para módulos v2+.
Quando subsistemas são lançados em cadências diferentes, têm conjuntos de consumidores diferentes ou precisam de linhas semver isoladas.
Permaneça com um único módulo enquanto os limites ainda estiverem fluidos.
go get -u promove requisitos para versões mais novas, mas builds normais ainda resolvem via MVS e suas linhas require registradas.
Leia a diferença antes de mesclar.
A biblioteca padrão é distribuída com a distribuição Go e não é um módulo separadamente baixável em builds normais.
Ela ainda usa as mesmas regras de pacotes e caminhos de importação.
Não - a regra do diretório internal é imposta pelo compilador para caminhos sob a raiz do seu módulo.
MVS eleva a versão selecionada para o mínimo que satisfaz ambos, a menos que você adicione diretivas replace ou exclude.
Não há herança em diamante como em alguns outros ecossistemas.
cmd, internal e pkg vãoVersões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 18 de jul. de 2026