Go Modules na Prática: Guia Completo

Go Modules é o sistema oficial de gerenciamento de dependências do Go desde a versão 1.11. Neste guia prático, você vai aprender tudo que precisa para dominar Go Modules no dia a dia.

O Que São Go Modules?

Go Modules é um sistema que:

• Gerencia dependências do seu projeto
• Controla versões de pacotes
• Garante builds reproduzíveis
• Elimina a necessidade do GOPATH

Cada projeto Go moderno é um “módulo” — uma coleção de pacotes Go versionados juntos.

Criando Seu Primeiro Módulo

Iniciando um Novo Projeto

# Crie uma pasta para seu projeto
mkdir meu-projeto
cd meu-projeto

# Inicialize o módulo
go mod init github.com/seuusuario/meu-projeto

Isso cria um arquivo go.mod:

module github.com/seuusuario/meu-projeto

go 1.25

Estrutura do go.mod

O arquivo go.mod contém:

• module: caminho do módulo (geralmente URL do repositório)
• go: versão mínima do Go necessária
• require: dependências diretas
• indirect: dependências indiretas (dependências das suas dependências)

Adicionando Dependências

Método 1: Import e go mod tidy

Simplesmente importe o pacote no seu código:

package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Olá!"})
    })
    r.Run()
}

Depois execute:

go mod tidy

O Go automaticamente:

1. Baixa a dependência
2. Adiciona ao go.mod
3. Cria/atualiza o go.sum

Método 2: go get

# Adiciona a versão mais recente
go get github.com/gin-gonic/gin

# Adiciona uma versão específica
go get github.com/gin-gonic/gin@v1.9.1

# Adiciona a última versão de uma major
go get github.com/gin-gonic/gin@v1

Entendendo Versões

Versionamento Semântico

Go Modules usa Semantic Versioning:

v1.2.3
│ │ │
│ │ └── Patch: correções de bugs
│ └──── Minor: novas features (compatível)
└────── Major: breaking changes (incompatível)

Versões Especiais

# Última versão estável
go get github.com/pkg/errors@latest

# Commit específico
go get github.com/pkg/errors@abc1234

# Branch específica
go get github.com/pkg/errors@master

# Versão v2+ (caminho diferente!)
go get github.com/pkg/errors/v2

Regra do v2+

Quando um módulo lança v2.0.0 ou maior, o caminho do import muda:

// v1.x
import "github.com/exemplo/pacote"

// v2.x
import "github.com/exemplo/pacote/v2"

Isso permite que v1 e v2 coexistam no mesmo projeto.

Comandos Essenciais

go mod tidy

go mod tidy

O comando mais usado! Ele:

• Adiciona dependências faltando
• Remove dependências não usadas
• Atualiza go.mod e go.sum

Execute sempre após modificar imports.

go mod download

go mod download

Baixa todas as dependências para o cache local. Útil para:

• CI/CD (pré-baixar deps)
• Trabalhar offline

go mod verify

go mod verify

Verifica se as dependências no cache correspondem aos hashes em go.sum. Detecta:

• Arquivos corrompidos
• Modificações maliciosas

go mod graph

go mod graph

Mostra a árvore de dependências. Útil para debugar conflitos de versão.

go mod why

go mod why github.com/pkg/errors

Explica por que uma dependência existe. Mostra o caminho de import.

go mod vendor

go mod vendor

Copia todas as dependências para uma pasta vendor/. Útil para:

• Builds offline
• Auditoria de código
• Ambientes restritos

O Arquivo go.sum

O go.sum contém hashes criptográficos de cada dependência:

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL...

Importante:

• Sempre commite go.sum no git
• Nunca edite manualmente
• Garante que todos usem exatamente as mesmas dependências

Atualizando Dependências

Atualizar Uma Dependência

# Atualiza para a última versão minor/patch
go get -u github.com/gin-gonic/gin

# Atualiza apenas patches
go get -u=patch github.com/gin-gonic/gin

# Atualiza para versão específica
go get github.com/gin-gonic/gin@v1.10.0

Atualizar Todas as Dependências

# Atualiza todas (minor/patch)
go get -u ./...

# Atualiza todas (apenas patches)
go get -u=patch ./...

Verificar Atualizações Disponíveis

go list -m -u all

Trabalhando com Módulos Privados

Configurando GOPRIVATE

Para módulos em repositórios privados:

# Variável de ambiente
export GOPRIVATE=github.com/minhaempresa/*

# Ou múltiplos padrões
export GOPRIVATE=github.com/minhaempresa/*,gitlab.com/interno/*

Isso faz o Go:

• Não usar o proxy público
• Não verificar no checksum database

Autenticação

Para repos privados no GitHub:

# Configurar git para usar token
git config --global url."https://SEU_TOKEN@github.com/".insteadOf "https://github.com/"

Ou use SSH:

git config --global url."git@github.com:".insteadOf "https://github.com/"

Replace e Exclude

Replace: Substituir Dependências

// go.mod
module meu-projeto

go 1.25

require github.com/pacote/original v1.0.0

// Usar fork local durante desenvolvimento
replace github.com/pacote/original => ../meu-fork

// Ou usar outro repo
replace github.com/pacote/original => github.com/meu/fork v1.0.1

Casos de uso:

• Desenvolvimento local de dependências
• Usar forks com fixes
• Substituir por versão compatível

Exclude: Bloquear Versões

// go.mod
module meu-projeto

exclude github.com/pacote/bugado v1.2.3

Força o Go a escolher outra versão.

Workspaces (Go 1.18+)

Para trabalhar com múltiplos módulos relacionados:

# Estrutura
projeto/
├── go.work
├── modulo-a/
│   └── go.mod
└── modulo-b/
    └── go.mod

# Criar workspace
go work init ./modulo-a ./modulo-b

Arquivo go.work:

go 1.25

use (
    ./modulo-a
    ./modulo-b
)

Isso permite desenvolver módulos interdependentes sem replace.

Importante: Não commite go.work — é para desenvolvimento local.

Dicas e Boas Práticas

1. Sempre Execute go mod tidy

Antes de commitar, sempre:

go mod tidy
git add go.mod go.sum
git commit -m "atualiza dependências"

2. Prefira Versões Estáveis

# Bom
go get github.com/pkg/errors@v0.9.1

# Evite (instável)
go get github.com/pkg/errors@master

3. Atualize Regularmente

Dependências desatualizadas acumulam vulnerabilidades. Agende atualizações mensais:

go get -u ./...
go mod tidy
go test ./...

4. Use go mod verify em CI

# .github/workflows/ci.yml
- name: Verify dependencies
  run: go mod verify

5. Documente Replaces

Se usar replace, comente o motivo:

// go.mod

// Temporário: aguardando merge do PR #123
replace github.com/lib/bugada => github.com/meu/fix v0.0.0-20240101

Troubleshooting

“module not found”

# Limpar cache
go clean -modcache

# Tentar novamente
go mod tidy

Conflito de versões

# Ver árvore de dependências
go mod graph | grep pacote-problema

# Forçar versão específica
go get pacote-problema@v1.2.3

Checksum mismatch

# Verificar
go mod verify

# Se falhar, limpar e rebaixar
go clean -modcache
go mod download

Conclusão

Go Modules simplifica drasticamente o gerenciamento de dependências em Go. Os comandos mais importantes para o dia a dia são:

1. go mod init — criar módulo
2. go mod tidy — sincronizar dependências
3. go get — adicionar/atualizar dependências

Com essas ferramentas, você tem controle total sobre as versões do seu projeto e builds 100% reproduzíveis.

Próximo passo: Aprenda sobre Testes em Go para garantir a qualidade do seu código.