Module Retraction
Como retrair versões problemáticas de módulos usando a diretiva retract (Go 1.16+)
O que é Module Retraction?
Module Retraction (Retração de Módulo) é um mecanismo introduzido no Go 1.16 que permite aos autores de módulos marcar versões como não recomendadas sem removê-las do repositório.
Quando Usar Retraction?
Use retraction quando:
✅ Publicou uma versão por acidente (ex: tag errada)
✅ Descobriu bug crítico ou falha de segurança após publicação
✅ Versão está quebrada em certas plataformas
✅ Versão contém código não finalizado que foi taggeado prematuramente
✅ Precisa desencorajar uso de uma versão específica
❌ Não use para depreciar um módulo inteiro (use comentário no README)
Sintaxe da diretiva 'retract'
Retrair uma única versão
module github.com/usuario/biblioteca
go 1.25
// Retrair uma versão específica
retract v1.2.0 // Bug crítico no sistema de autenticaçãoRetrair um intervalo de versões
Múltiplas retrações
Como funciona?
1. Autor retrai a versão
2. Usuários são alertados
3. Comandos go evitam versões retraídas
Exemplos práticos
Exemplo 1: Versão publicada acidentalmente
Exemplo 2: Bug crítico de segurança
Exemplo 3: Incompatibilidade de plataforma
Exemplo 4: Retrair a própria versão de retração
Visualizando retrações
Listar versões com retrações
Ver motivo da retração
Verificar dependências retraídas
Comportamento dos comandos
go get <module>@latest
Pula versões retraídas
go get <module>@v1.2.0
Permite mas mostra aviso
go get -u
Atualiza para versão não retraída
go list -m -u all
Mostra quais deps são retraídas
go mod tidy
Mantém versão atual, mesmo se retraída
go install <module>@latest
Pula versões retraídas
Diferença: retraction vs deprecation
Escopo
Versões específicas
Módulo inteiro ou pacote
Mecanismo
Diretiva retract no go.mod
Comentário no código
Detecção
Automática pelo comando go
Manual (leitura de docs)
Ação
Versões evitadas automaticamente
Desenvolvedores decidem migrar
Desde
Go 1.16
Sempre (via documentação)
Exemplo de deprecation
Workflow de retraction
Passo a passo completo
Retraction em 'go.sum'
Versões retraídas permanecem no go.sum:
Isso é intencional - builds antigos continuam funcionando.
Limitações
O que retraction NÃO Faz
❌ Não remove a versão do repositório git ❌ Não remove a versão do module proxy ❌ Não força atualização automática ❌ Não impede uso se explicitamente solicitado (@v1.5.0) ❌ Não funciona com Go <1.16
O que retraction FAZ
✅ Mostra avisos ao tentar usar ✅ Evita seleção automática em go get @latest ✅ Documenta problemas conhecidos ✅ Guia desenvolvedores para versões corretas
Melhores práticas
✅ Faça
Sempre inclua comentário explicativo na retraction
Seja específico sobre o problema e solução
Publique versão corrigida junto com retraction
Documente retraction em release notes
Comunique proativamente usuários conhecidos
Use para problemas sérios, não pequenos bugs
❌ Não Faça
Retrair versões sem publicar correção
Usar retraction para forçar upgrades
Retrair sem explicação clara
Retrair frequentemente (sugere processo de release ruim)
Confiar apenas em retraction para segurança (emita CVE também)
Integração com ferramentas
GitHub/GitLab
Retraction funciona perfeitamente com:
✅ Git tags
✅ GitHub Releases
✅ GitLab Releases
✅ Security Advisories
Proxies de módulos
✅ proxy.golang.org respeita retractions
✅ Proxies customizados (Athens, etc.) suportam
✅ Caches privados mantêm versões retraídas
IDEs
✅ VS Code (com gopls) mostra avisos
✅ GoLand destaca versões retraídas
✅ Ferramentas de linting detectam uso
Troubleshooting
Problema: Usuários ainda usando versão retraída
Problema: Retraction não aparece
Problema: Como "desretrair" uma versão
Recursos adicionais
Conclusão
Module Retraction é uma ferramenta essencial para manter a qualidade do ecossistema Go:
🛡️ Protege usuários de versões problemáticas
📢 Comunica problemas automaticamente
🔄 Mantém compatibilidade (não quebra builds)
✨ Guia para versões corretas
Não tenha medo de retrair versões problemáticas! É melhor documentar e guiar usuários do que deixá-los descobrir problemas sozinhos.
Last updated