staticcheck & golangci-lint en CI

staticcheck es un analizador de alta señal para errores y mal uso de API.

golangci-lint ejecuta staticcheck y docenas de otras comprobaciones detrás de un único archivo de configuración, lo que lo convierte en el punto de entrada habitual de CI para la política de linting de Go.

Resumen

Los editores locales proporcionan retroalimentación rápida; la CI aplica las mismas reglas para cada contribuidor y bot.

Comienza con go vet y staticcheck, luego añade golangci-lint con un .golangci.yml confirmado.

Adopta nuevas comprobaciones incrementalmente en repositorios heredados para que los equipos corrijan los hallazgos en lugar de deshabilitar linters permanentemente.

Receta

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

go install honnef.co/go/tools/cmd/staticcheck@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
 
staticcheck ./...
golangci-lint run ./...

.golangci.yml mínimo:

run:
  timeout: 5m
linters:
  enable:
    - govet
    - staticcheck
    - ineffassign
    - unused
issues:
  max-issues-per-linter: 0

Cuándo usar esto:

• Estandarizar el linting en microservicios de una organización.
• Convertir comentarios de revisión ("revisar retorno de error") en fallos automatizados.
• Elevar el nivel después de go vet con comprobaciones de corrección (reglas SA* de staticcheck).
• Bloquear lanzamientos hasta que no haya problemas de linter.

Ejemplo de Trabajo

Handler problemático:

// example.com/demo/internal/api/handler.go
package api
 
import (
    "fmt"
    "net/http"
)
 
func Health(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "ok") // falta comprobación de error
    defer r.Body.Close() // Body puede ser nil en GET
}

staticcheck localmente:

staticcheck ./internal/api/...

Los hallazgos típicos incluyen errores mal manejados y construcciones sospechosas.

Conecta la CI con golangci-lint:

name: lint
on: [push, pull_request]
jobs:
  golangci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
      - run: go mod download
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest
          args: ./...

Handler corregido:

func Health(w http.ResponseWriter, r *http.Request) {
    if _, err := fmt.Fprintf(w, "ok"); err != nil {
        http.Error(w, "write failed", http.StatusInternalServerError)
        return
    }
    if r.Body != nil {
        defer r.Body.Close()
    }
}

Lo que esto demuestra:

• staticcheck marca problemas reales de corrección/estilo más allá del formato.
• golangci-lint-action ejecuta la misma configuración que los contribuidores usan localmente.
• Las correcciones son Go ordinario - los linters codifican políticas que pedirías en una revisión.

Inmersión Profunda

Cómo Funciona

• Los analizadores usan go/analysis (directa o indirectamente) para inspeccionar ASTs tipados.
• golangci-lint carga los linters habilitados, los ejecuta en paralelo por paquete y agrega los problemas.
• El código de salida es distinto de cero cuando los problemas superan los límites configurados (max-issues-per-linter).

Puntos Destacados de staticcheck

Ejecuta staticcheck -explain SA1006 (código de ejemplo) para leer la documentación de la regla.

Perillas de Configuración de golangci-lint

Adopción de Línea Base en Repositorios Existentes

1. Ejecuta golangci-lint run ./... > baseline.txt y corrige primero los paquetes críticos.
2. Habilita issues.new-from-rev: origin/main para que la deuda heredada no bloquee cada PR.
3. Reduce la línea base en tareas dedicadas; aprieta a cero a lo largo de los sprints.
4. Evita comentarios nolint generales - requiere IDs de ticket cuando las excepciones son inevitables.

Notas de Go

run:
  go: "1.26"
  build-tags:
    - integration

Empareja los tags con los trabajos de prueba que usan -tags=integration.

Trampas

• Diferentes versiones de golangci-lint localmente vs CI - Los conjuntos de reglas divergen. Solución: Fija la versión en la acción de CI y documenta el comando de instalación para los desarrolladores.
• Directivas nolint demasiado amplias - //nolint:all oculta errores futuros. Solución: Nombra linters específicos y justifica en el comentario.
• Ejecutar linters sin descarga de módulos - Falsos negativos o errores de carga. Solución: go mod download antes del trabajo de linting.
• Excluir archivos de prueba por completo - Las pruebas ocultan patrones de race conditions. Solución: Haz linting de las pruebas también; usa issues.exclude-rules solo para rutas ruidosas conocidas.
• max-issues cero desde el primer día - Los equipos deshabilitan la CI. Solución: Usa new-from-rev o el modo de advertencia temporal.
• Ignorar las deprecaciones de staticcheck - Las futuras versiones de Go eliminan símbolos. Solución: Trata SA1019 (obsoleto) como errores en las bibliotecas.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Configuración de Herramientas de Go - instala staticcheck y golangci-lint
• gosec & nilaway para Seguridad y Seguridad Nil - analizadores de seguridad y nil
• govulncheck para Vulnerabilidades de Dependencias - escaneo de CVE de dependencias
• Escribir Analizadores Personalizados de go/analysis - reglas específicas del equipo
• Mejores Prácticas de gopls y Herramientas de Análisis - alineación del editor y la CI

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