Go Modules: Gerenciando Dependências
Desde Go 1.11, Go Modules é o sistema oficial para gerenciamento de dependências em Go. Antes disso, usávamos GOPATH e ferramentas como dep e glide, mas hoje Go Modules é a forma padrão e recomendada.
O Básico
Criando um Módulo
# Crie um diretório para seu projeto
mkdir meu-projeto
cd meu-projeto
# Inicialize o módulo
go mod init github.com/seuuser/meu-projeto
Isso cria um arquivo go.mod:
module github.com/seuuser/meu-projeto
go 1.23
Adicionando Dependências
# Adicionar uma dependência específica
go get github.com/gin-gonic/gin@v1.9.1
# Adicionar a versão mais recente
go get github.com/gin-gonic/gin@latest
# Adicionar dependências do código (ao importar)
go mod tidy
O go.mod é atualizado automaticamente:
module github.com/seuuser/meu-projeto
go 1.23
require (
github.com/gin-gonic/gin v1.9.1
)
Entendendo os Arquivos
go.mod
Define o módulo e suas dependências:
module github.com/seuuser/meu-projeto
go 1.23
require (
github.com/gin-gonic/gin v1.9.1
github.com/lib/pq v1.10.9
)
require (
// Dependências indiretas (das suas dependências)
github.com/bytedance/sonic v1.10.0 // indirect
)
go.sum
Contém checksums criptográficos de cada dependência:
github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5c...
github.com/gin-gonic/gin v1.9.1/go.mod h1:RDnlIIZ...
Sempre commite go.sum — ele garante builds reproduzíveis.
Comandos Essenciais
| Comando | Descrição |
|---|---|
go mod init | Cria novo módulo |
go mod tidy | Sincroniza dependências com o código |
go get pkg@version | Adiciona/atualiza dependência |
go mod download | Baixa dependências para cache |
go mod verify | Verifica integridade das dependências |
go mod graph | Mostra grafo de dependências |
go mod why pkg | Explica por que pkg é dependência |
Versionamento Semântico
Go Modules usa Semantic Versioning:
v1.2.3— versão estávelv0.x.x— versão de desenvolvimento (pode quebrar)v2.0.0— breaking change (requer import diferente)
Import Paths com v2+
Para versões v2 ou superior, o import path muda:
import "github.com/example/pkg" // v0.x ou v1.x
import "github.com/example/pkg/v2" // v2.x
import "github.com/example/pkg/v3" // v3.x
Trabalhando com Versões
Atualizando Dependências
# Atualizar uma dependência específica
go get github.com/gin-gonic/gin@v1.10.0
# Atualizar todas para patch versions
go get -u=patch ./...
# Atualizar todas para minor versions
go get -u ./...
Listando Versões Disponíveis
go list -m -versions github.com/gin-gonic/gin
# github.com/gin-gonic/gin v1.1.0 v1.1.1 ... v1.9.1 v1.10.0
Downgrade
go get github.com/gin-gonic/gin@v1.8.0
Módulos Privados
Para repositórios privados:
# Configurar acesso (adicione ao ~/.bashrc ou ~/.zshrc)
export GOPRIVATE=github.com/minhaempresa/*
# Para GitLab ou Bitbucket
export GOPRIVATE=gitlab.com/minhaempresa/*,bitbucket.org/minhaempresa/*
Usando SSH ao invés de HTTPS
git config --global url."git@github.com:".insteadOf "https://github.com/"
Desenvolvimento Local
Replace Directive
Para usar uma versão local de uma dependência:
// go.mod
replace github.com/outra/lib => ../minha-lib-local
Útil para:
- Debugging de dependências
- Desenvolvimento simultâneo de múltiplos módulos
- Forks temporários
Workspace (Go 1.18+)
Para projetos com múltiplos módulos:
# Criar workspace
go work init ./modulo1 ./modulo2
# Adicionar módulo
go work use ./modulo3
Isso cria go.work:
go 1.23
use (
./modulo1
./modulo2
./modulo3
)
Boas Práticas
1. Sempre Use go mod tidy
# Antes de commit
go mod tidy
Remove dependências não usadas e adiciona as faltantes.
2. Commite go.sum
O go.sum garante que todos usem as mesmas versões exatas.
3. Atualize Regularmente
# Verifique vulnerabilidades
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
4. Use Versões Específicas em Produção
# Evite @latest em produção
go get github.com/pkg/errors@v0.9.1 # ✓
go get github.com/pkg/errors@latest # ✗
5. Minimize Dependências
Menos dependências = menos superfície de ataque e menos problemas de compatibilidade.
Troubleshooting
Cache Corrompido
go clean -modcache
Checksum Mismatch
# Forçar re-download
go mod download -x
Dependência não Encontrada
# Verificar proxy
echo $GOPROXY
# Padrão: https://proxy.golang.org,direct
Recursos
Veja também
- Go para Iniciantes — Primeiro programa e instalação
- API REST com Go — Use modules num projeto real
- Go com Docker — Deploy com multi-stage build
- Testes em Go — Teste seu módulo com go test
- Go Cheatsheet — Referência rápida de comandos Go
Última atualização: Fevereiro 2026