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

10 exemplos para você começar com Pacotes e Módulos - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Crie um diretório de workspace: mkdir moddemo && cd moddemo.
• Inicialize um módulo: go mod init example.com/moddemo.
• Execute os trechos do diretório raiz do módulo com go run . após salvá-los como main.go (ou o caminho mostrado).

Exemplos Básicos

1. Inicialize um módulo

go mod init grava o go.mod com o caminho do seu módulo.

// Execute primeiro no shell:
// go mod init example.com/moddemo

• O caminho do módulo deve corresponder a onde o código será hospedado (ou use example.com/... para aprendizado).
• go.mod é a raiz versionada para cada pacote sob esta árvore de diretórios.
• Subdiretórios adicionam segmentos ao caminho de importação; eles não precisam de seu próprio go.mod, a menos que você divida módulos.

Relacionado: Pacotes e Módulos: A Unidade de Distribuição do Go - modelo mental de pacotes vs. módulos

2. Crie e importe um pacote local

Divida o código entre pacotes dentro do mesmo módulo.

// greet/greet.go
package greet
 
import "fmt"
 
func Hello(name string) string {
    return fmt.Sprintf("hello, %s", name)
}

// main.go
package main
 
import (
    "fmt"
    "example.com/moddemo/greet"
)
 
func main() {
    fmt.Println(greet.Hello("Go"))
}

• O caminho de importação é caminho do módulo + /diretório.
• Apenas nomes exportados (capitalizados) são visíveis fora do pacote.
• Execute a partir da raiz do módulo: go run .

Relacionado: Nomenclatura de Pacotes e Diretórios internal/ - regras de nomenclatura e visibilidade

3. Adicione uma dependência

go get registra um requisito semver em go.mod.

go get github.com/google/uuid@latest

package main
 
import (
    "fmt"
    "github.com/google/uuid"
)
 
func main() {
    fmt.Println(uuid.NewString())
}

• go get atualiza go.mod e go.sum.
• As compilações baixam módulos para o cache de módulos automaticamente.
• Fixe uma versão específica com @v1.6.0 em vez de @latest.

Relacionado: go.mod, go.sum e Seleção Mínima de Versão - como as versões são resolvidas

4. Limpe o grafo de módulos

Remova requisitos não utilizados e adicione os ausentes.

go mod tidy

• Execute após refatorações que adicionam ou removem importações.
• O CI deve falhar se go mod tidy alterar arquivos - use go mod tidy -diff ou ganchos de commit.
• Mantém go.sum alinhado com as importações reais.

Relacionado: Melhores Práticas de Pacotes, Módulos e Layout de Projeto - hábitos de higiene

5. Liste as versões dos módulos

Inspecione o que a toolchain selecionou.

go list -m all
go list -m -versions github.com/google/uuid

• all imprime a lista de compilação para o módulo atual.
• -versions consulta as tags disponíveis da origem (requer rede).
• Útil ao depurar atualizações inesperadas.

Relacionado: Diretivas Pseudo-Versões, replace e retract - substituições e lançamentos ruins

6. Use internal/ para pacotes privados

internal/ bloqueia importações de fora da árvore pai.

moddemo/
  go.mod
  cmd/app/main.go
  internal/config/config.go

// internal/config/config.go
package config
 
const Port = 8080

// cmd/app/main.go
package main
 
import (
    "fmt"
    "example.com/moddemo/internal/config"
)
 
func main() {
    fmt.Println(config.Port)
}

• Código fora de example.com/moddemo não pode importar internal/config.
• Prefira internal/ em vez de comentários para APIs "não usar".
• Mantém a área de superfície pública pequena para bibliotecas.

Relacionado: Layout Padrão de Projeto para Serviços e Bibliotecas - layout cmd e internal

7. Importação em branco para efeitos colaterais de registro

Importe apenas para init, não para uso direto de símbolos.

package main
 
import (
    "fmt"
    _ "example.com/moddemo/register" // aciona init no pacote register
)
 
func main() {
    fmt.Println("drivers registered")
}

// register/register.go
package register
 
func init() {
    // registra plugin, driver ou manipulador http
}

• A importação em branco executa funções init na ordem de dependência.
• Comum para drivers de banco de dados (_ "github.com/lib/pq") e formatos de imagem.
• Não use quando precisar chamar funções exportadas do pacote.

Relacionado: Ciclos de Importação, Importações em Branco e Importações Dot - quando as importações de efeitos colaterais se encaixam

Exemplos Intermediários

8. Substituição local para um fork ou módulo irmão

Aponte um requisito para um caminho local durante o desenvolvimento.

// trecho de go.mod
module example.com/moddemo
 
go 1.26
 
require example.com/lib v0.0.0
 
replace example.com/lib => ../lib

• replace é para desenvolvimento; evite confirmar caminhos específicos da máquina em branches principais compartilhadas sem documentação.
• Os consumidores do seu módulo publicado não veem caminhos replace não publicados no seu laptop, a menos que você os confirme.
• Use go.work para repositórios multi-módulo quando vários módulos se editam diariamente.

Relacionado: go work: Modo Workspace para Repositórios Multi-Módulo - workspace sem hacks de replace

9. Modo Workspace com go.work

Desenvolva múltiplos módulos juntos sem editar o go.mod de cada um.

# Do diretório raiz do repositório com módulos irmãos app/ e lib/
go work init ./app ./lib
go work use ./app ./lib

// app/go.mod
module example.com/app
 
go 1.26
 
require example.com/lib v0.0.0

• go.work se aplica apenas na sua máquina; não o publique como o contrato da biblioteca.
• GOWORK=off força o modo apenas de módulo para comparações de CI reproduzíveis.
• Adicione linhas use à medida que novos módulos entram no monorepo.

Relacionado: go work: Modo Workspace para Repositórios Multi-Módulo - fluxo de trabalho completo do workspace

10. Esboço do layout padrão de serviço

main fina, lógica em pacotes, código privado em internal/.

myapp/
  go.mod
  cmd/myapp/main.go
  internal/server/server.go
  pkg/client/client.go   // opcional: API pública estável para outros repositórios

// cmd/myapp/main.go
package main
 
import "example.com/myapp/internal/server"
 
func main() {
    server.Run()
}

• cmd/ contém um diretório por binário; cada um é package main.
• internal/ é estritamente privado; pkg/ é uma API pública convencional (ainda é sua escolha suportar).
• Um módulo pode distribuir múltiplos comandos sob cmd/.

Relacionado: Layout Padrão de Projeto para Serviços e Bibliotecas - orientação completa de layout

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

636f64656775696465732e696f7c6367696f3530387c323032363037