Configuración de golangci-lint

golangci-lint ejecuta muchos analizadores de Go detrás de un único archivo de configuración y una única CLI.

Los equipos utilizan .golangci.yml para elegir linters, establecer la severidad, excluir árboles generados y mantener las ejecuciones locales alineadas con CI.

Receta

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

# Instalar versión fijada (coincidir con CI)
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.6
 
# Inicializar configuración interactivamente
golangci-lint config verify
 
# Ejecutar con la configuración del repositorio
golangci-lint run ./...
 
# Corregir automáticamente lo que sea seguro
golangci-lint run --fix ./...

Cuándo usar esto:

• go vet está limpio pero la revisión todavía detecta los mismos problemas de staticcheck.
• Incorporación de múltiples servicios a una política de linter de plataforma única.
• Ajuste del ruido de protobuf, mocks o vendor/.
• División de trabajos de lint por módulo en un monorepo go.work.

Ejemplo de Trabajo

.golangci.yml de inicio para un módulo de servicio único:

run:
  timeout: 5m
  modules-download-mode: readonly
 
linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gosec
    - revive
    - bodyclose
  disable-all: true
 
linters-settings:
  govet:
    enable-all: true
  revive:
    rules:
      - name: exported
        disabled: true
  gosec:
    excludes:
      - G104 # ruidoso para fmt.Fprintf a http.ResponseWriter
 
issues:
  exclude-dirs:
    - vendor
    - third_party
  exclude-files:
    - ".*\\.pb\\.go$"
    - ".*_mock\\.go$"
  max-issues-per-linter: 0
  max-same-issues: 0

Makefile:

GOLANGCI_LINT_VERSION ?= v2.1.6
 
.PHONY: lint
lint:
	golangci-lint run ./...

Trabajo de CI:

- uses: actions/setup-go@v5
  with:
    go-version: '1.26.x'
- name: golangci-lint
  uses: golangci/golangci-lint-action@v6
  with:
    version: v2.1.6
    args: ./...

Lo que esto demuestra:

• disable-all: true y luego enable explícito mantiene el conjunto intencional.
• exclude-files omite protobuf y mocks generados.
• Fijar la versión en Makefile, acción y documentación evita la deriva de "funciona localmente".

Análisis Profundo

Cómo Funciona

• golangci-lint carga los paquetes una vez y ejecuta los linters habilitados en paralelo cuando es seguro.
• Cada linter envuelve herramientas upstream (staticcheck, gosec, revive, etc.).
• Los hallazgos se fusionan en un único informe con prefijo de nombre de linter (staticcheck, govet, ...).
• La configuración puede residir en la raíz del repositorio; los módulos hijos pueden tener anulaciones.

Progresión Recomendada de Habilitación

Patrones de Monorepo

# Raíz: valores predeterminados compartidos
run:
  relative-path-mode: gomod
 
issues:
  exclude-dirs:
    - vendor

services/billing/.golangci.yml por módulo:

linters:
  enable:
    - gosec
linters-settings:
  gosec:
    severity: medium

Ejecutar desde la raíz del espacio de trabajo:

golangci-lint run ./services/billing/...
golangci-lint run ./services/...   # todos los módulos con go.mod

Supresiones

//nolint:gosec // G304: ruta validada por el contrato del llamador; ver SEC-123
os.Open(userPath)

Prefiere //nolint específico con ticket sobre expresiones regulares amplias de exclude-rules.

Notas de Go

# Verificar sintaxis de configuración
golangci-lint config verify
 
# Listar linters habilitados
golangci-lint linters
 
# Depurar un solo linter
golangci-lint run --disable-all -E staticcheck ./...

Trampas Comunes

• golangci-lint no fijado en CI - Los nuevos lanzamientos habilitan linters por defecto. Solución: Fija la versión en la acción y documenta el proceso de actualización.
• Linting de monorepo completo sin tiempos de espera - Repositorios grandes agotan la memoria o alcanzan el valor predeterminado de 1 minuto. Solución: Establece run.timeout: 5m y divide por módulo en la matriz de CI.
• Excluir demasiado con regex - Oculta errores reales en internal/legacy. Solución: Exclusión por tiempo limitado con ticket de refactorización.
• Ejecutar --fix ciegamente en CI - La corrección automática puede cambiar la semántica de algunos linters. Solución: Ejecuta --fix localmente o en PRs de bots, no en commits principales silenciosos.
• Versión de Go no coincidente - Los linters usan información de tipo de la directiva go del módulo. Solución: go-version de CI coincide con go.mod.
• Duplicación de vet a través de go vet y golangci-lint - Redundante pero aceptable; elimina go vet independiente si govet enable-all está activado.

Alternativas

Preguntas Frecuentes

Relacionado

• go vet y Diagnósticos de Analizadores Comunes - mensajes de vet explicados
• staticcheck y golangci-lint en CI - patrones de integración de CI
• Puertas de Calidad de CI: Lint, Test, Race, Vuln - ubicación del trabajo de lint
• Hooks de Pre-commit y Listas de Verificación de Revisión - alcance del lint local
• Prácticas Recomendadas de Linting y Calidad de Código - reglas de adopción

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).