gopls: Navegación, Refactorización y Diagnósticos

gopls es el servidor de lenguaje oficial de Go.

Convierte tu editor en un cliente consciente de tipos: salta a definiciones, renombra símbolos en paquetes, muestra diagnósticos y aplica correcciones antes de ejecutar go build.

Resumen

gopls carga tu módulo (o espacio de trabajo go.work), verifica tipos de paquetes incrementalmente y responde a solicitudes LSP del editor.

Los comandos de navegación se resuelven a través del verificador de tipos, por lo que respetan las importaciones, las etiquetas de compilación y los genéricos.

Las operaciones de refactorización (renombrar, agregar importación, extraer función) editan el AST con parches verificados por tipos en lugar de búsqueda y reemplazo ciegos.

Los diagnósticos combinan errores del compilador de go/types con analizadores seleccionados (variables no utilizadas, errores de printf, y más).

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

Acciones del editor (los nombres varían según el IDE):

Cuándo usar esto:

• Rastrear un símbolo desde el manejador HTTP hasta la implementación de la tienda en varios paquetes.
• Renombrar una función exportada sin perder importadores.
• Corregir ciclos de importación e importaciones no utilizadas antes de confirmar.
• Leer subrayados que reflejan problemas de go build y estilo vet de forma temprana.

Ejemplo de trabajo

Considera un módulo pequeño:

// 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"))
}

Con gopls ejecutándose en la raíz del módulo:

1. Ir a la definición en greet.Hello en main.go abre greet.go en el cuerpo de la función.
2. Buscar referencias en Hello lista main.go y cualquier archivo de prueba que importe greet.
3. Renombrar Hello a Greet actualiza ambos archivos y ajusta el uso de importaciones si el símbolo cambia de paquete (gopls puede solicitar o rechazar si esto rompiera la visibilidad).
4. Organizar importaciones elimina fmt no utilizado si eliminas el println, agrega importaciones faltantes cuando referencias nuevos paquetes.

Lo que esto demuestra:

• La navegación entre paquetes sigue las rutas de importación, no la proximidad del directorio.
• Renombrar es seguro porque gopls conoce todas las referencias a partir de metadatos verificados por tipos.
• Los diagnósticos aparecen en importaciones no utilizadas y llamadas con aridad incorrecta antes de go run.

Inmersión Profunda

Cómo Funciona

• gopls mantiene una sesión por raíz de espacio de trabajo (go.mod o go.work).
• Los cambios de archivo desencadenan la recomputación incremental de la sintaxis y los tipos del paquete.
• Los clientes LSP envían posiciones basadas en URI; gopls las mapea a nodos AST y objetos de tipo.
• Los resultados se almacenan en caché; los paquetes sin cambios omiten el reprocesamiento.

Funciones de Navegación

Funciones de Refactorización

Diagnósticos y Acciones de Código

gopls publica diagnósticos con severidad (error, advertencia, pista).

Muchos incluyen acciones de código: correcciones rápidas para importaciones faltantes, tipos sugeridos o refactorizaciones triviales.

Los diagnósticos del analizador aproximan go vet y similares; no se garantiza que coincidan con todos los linters que habilites más adelante.

Notas de Go

// las etiquetas de compilación afectan lo que gopls verifica
//go:build integration
 
package myapp

Alinea gopls.build.buildFlags o GOFLAGS con la CI para que los archivos etiquetados no cambien de verde localmente a rojo en CI.

Trampas

• Raíz de espacio de trabajo incorrecta - Abrir una carpeta principal sin go.mod deja a gopls adivinando; abre el directorio del módulo o go.work. Solución: Archivo → Abrir Carpeta en la raíz del módulo.
• Diagnósticos obsoletos después de cambiar de rama git - La caché de gopls puede estar desactualizada. Solución: Reinicia el servidor de lenguaje o ejecuta "Go: Restart Language Server" en VS Code.
• Renombrar entre módulos sin espacio de trabajo - Sin go.work o una versión publicada, el renombrado entre módulos puede estar incompleto. Solución: Agrega go.work para ediciones locales de varios módulos.
• Desajuste de etiquetas de compilación - Los archivos detrás de las etiquetas //go:build se muestran como excluidos o con errores en el editor. Solución: Establece buildFlags: ["-tags=integration"] en la configuración de gopls para que coincida con la CI.
• Ruido en el código generado - La salida de protobuf o stringer contamina la navegación. Solución: Excluye *.pb.go de las funciones del editor o marca los directorios generados en los filtros de directorio de gopls.
• Brecha entre gopls y golangci-lint - El editor puede estar limpio mientras la CI falla con linters más estrictos. Solución: Ejecuta golangci-lint run localmente con la configuración confirmada.

Alternativas

Preguntas Frecuentes

Relacionado

• Herramientas para Desarrolladores de Go: LSP, Depurador y Analizadores - descripción general de la cadena de herramientas
• Conceptos Básicos de Configuración de Herramientas de Go - instala y configura gopls
• Depuración con Delve - inspección en tiempo de ejecución cuando los tipos no son suficientes
• staticcheck y golangci-lint en CI - analizadores de CI más allá del subconjunto del editor
• Mejores Prácticas de gopls y Herramientas de Análisis - higiene del editor de equipo

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, modernizadores de go fix - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).