gopls: Navegação, Refatoração e Diagnósticos

gopls é o servidor oficial de linguagem Go.

Ele transforma seu editor em um cliente ciente de tipos: pule para definições, renomeie símbolos entre pacotes, exiba diagnósticos e aplique correções antes de executar go build.

Resumo

O gopls carrega seu módulo (ou workspace go.work), verifica tipos de pacotes incrementalmente e responde a requisições LSP do editor.

Comandos de navegação resolvem através do verificador de tipos, portanto, respeitam imports, tags de build e genéricos.

Operações de refatoração (renomear, adicionar import, extrair função) editam a AST com patches verificados por tipo em vez de busca e substituição cegas.

Diagnósticos mesclam erros do compilador de go/types com analisadores selecionados (variáveis não utilizadas, erros de printf e mais).

Receita

Cartão de referência rápida - pronto para copiar e colar.

Ações do editor (nomes variam por IDE):

Quando usar isso:

• Rastrear um símbolo de um manipulador HTTP para a implementação do armazenamento entre pacotes.
• Renomear uma função exportada sem perder importadores.
• Corrigir ciclos de importação e imports não utilizados antes do commit.
• Ler "rabiscos" que espelham problemas de go build e estilo vet precocemente.

Exemplo de Trabalho

Considere um pequeno módulo:

// example.com/demo/internal/greet/greet.go
package greet
 
func Hello(name string) string {
    return "hello, " + name
}

// example.com/demo/cmd/app/main.go
package main
 
import (
    "fmt"
    "example.com/demo/internal/greet"
)
 
func main() {
    fmt.Println(greet.Hello("world"))
}

Com o gopls em execução na raiz do módulo:

1. Ir para definição em greet.Hello em main.go abre greet.go no corpo da função.
2. Encontrar referências em Hello lista main.go e quaisquer arquivos de teste que importam greet.
3. Renomear Hello para Greet atualiza ambos os arquivos e ajusta o uso de importações se o símbolo mudar de pacote (o gopls pode solicitar ou recusar se isso quebrar a visibilidade).
4. Organizar imports remove fmt não utilizado se você excluir o println, adiciona imports ausentes quando você referencia novos pacotes.

O que isso demonstra:

• A navegação entre pacotes segue caminhos de importação, não proximidade de diretório.
• Renomear é seguro porque o gopls conhece todas as referências de metadados verificados por tipo.
• Diagnósticos aparecem em imports não utilizados e chamadas com aridade incorreta antes de go run.

Mergulho Profundo

Como Funciona

• O gopls mantém uma sessão por raiz de workspace (go.mod ou go.work).
• Mudanças de arquivo acionam recomputação incremental da sintaxe e tipos de pacotes.
• Clientes LSP enviam posições baseadas em URI; o gopls as mapeia para nós AST e objetos de tipo.
• Resultados são cacheados; pacotes inalterados pulam o retrabalho.

Recursos de Navegação

Recursos de Refatoração

Diagnósticos e Ações de Código

O gopls publica diagnósticos com severidade (erro, aviso, dica).

Muitos incluem ações de código: correções rápidas para imports ausentes, tipos sugeridos ou refatorações triviais.

Diagnósticos de analisadores aproximam go vet e similares; eles não são garantidos para corresponder a todos os linters que você habilitar posteriormente.

Notas Go

// tags de build afetam o que o gopls verifica
//go:build integration
 
package myapp

Alinhe gopls.build.buildFlags ou GOFLAGS com a CI para que arquivos marcados não alternem entre verde localmente e vermelho na CI.

Armadilhas

• Raiz do workspace incorreta - Abrir uma pasta pai sem go.mod deixa o gopls adivinhando; abra o diretório do módulo ou go.work. Correção: Arquivo → Abrir Pasta na raiz do módulo.
• Diagnósticos desatualizados após troca de branch git - O cache do gopls pode estar atrasado. Correção: Reinicie o servidor de linguagem ou execute "Go: Restart Language Server" no VS Code.
• Renomear entre módulos sem workspace - Sem go.work ou uma versão publicada, a renomeação entre módulos pode ser incompleta. Correção: Adicione go.work para edições locais de múltiplos módulos.
• Discrepância de tags de build - Arquivos atrás de tags //go:build aparecem como excluídos ou com erro no editor. Correção: Defina buildFlags: ["-tags=integration"] nas configurações do gopls para corresponder à CI.
• Ruído de código gerado - Saídas de protobuf ou stringer poluem a navegação. Correção: Exclua *.pb.go dos recursos do editor ou marque diretórios gerados nos filtros de diretório do gopls.
• Lacuna gopls vs golangci-lint - O editor pode estar limpo enquanto a CI falha em linters mais rigorosos. Correção: Execute golangci-lint run localmente com a configuração commitada.

Alternativas

FAQs

Relacionado

• Ferramentas de Desenvolvedor Go: LSP, Debugger e Analisadores - visão geral da toolchain
• Noções Básicas de Configuração de Ferramentas Go - instale e configure o gopls
• Depuração com Delve - inspeção em tempo de execução quando tipos não são suficientes
• staticcheck & golangci-lint na CI - analisadores de CI além do subconjunto do editor
• Boas Práticas de gopls e Ferramentas de Análise - higiene do editor de equipe

Versões da Pilha: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação), e golangci-lint (última - verifique o conjunto de linters na compilação).