staticcheck & golangci-lint em CI

staticcheck é um analisador de alto sinal para bugs e uso incorreto de APIs.

golangci-lint executa staticcheck e dezenas de outras verificações por trás de um único arquivo de configuração, tornando-o o ponto de entrada usual de CI para políticas de lint em Go.

Resumo

Editores locais fornecem feedback rápido; CI impõe as mesmas regras para todos os contribuidores e bots.

Comece com go vet e staticcheck, depois adicione golangci-lint com um .golangci.yml commitado.

Adote novas verificações incrementalmente em repositórios legados para que as equipes corrijam os achados em vez de desabilitar linters permanentemente.

Receita

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

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

Quando usar isso:

• Padronizar lint entre microsserviços em uma organização.
• Transformar comentários de revisão ("verificar retorno de erro") em falhas automatizadas.
• Elevar o padrão após go vet com verificações de corretude (regras SA* do staticcheck).
• Bloquear lançamentos com zero problemas de linter.

Exemplo de Trabalho

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 verificação de erro
    defer r.Body.Close() // Body pode ser nil em GET
}

staticcheck localmente:

staticcheck ./internal/api/...

Achados típicos incluem erros não tratados e construções suspeitas.

Integre CI com 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 corrigido:

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()
    }
}

O que isso demonstra:

• staticcheck sinaliza problemas reais de corretude/estilo além da formatação.
• golangci-lint-action executa a mesma configuração que os contribuidores usam localmente.
• Correções são Go comum - linters codificam políticas que você pediria em uma revisão.

Mergulho Profundo

Como Funciona

• Analisadores usam go/analysis (direta ou indiretamente) para inspecionar ASTs tipados.
• golangci-lint carrega os linters habilitados, executa-os em paralelo por pacote e agrega os problemas.
• Código de saída não zero quando os problemas excedem os limites configurados (max-issues-per-linter).

Destaques do staticcheck

Execute staticcheck -explain SA1006 (exemplo de código) para ler a documentação da regra.

Botões de Configuração do golangci-lint

Adoção de Baseline em Repositórios Brownfield

1. Execute golangci-lint run ./... > baseline.txt e corrija os pacotes críticos primeiro.
2. Habilite issues.new-from-rev: origin/main para que a dívida legada não bloqueie todos os PRs.
3. Reduza o baseline em tarefas dedicadas; aperte para zero ao longo de sprints.
4. Evite comentários genéricos nolint - exija IDs de ticket quando exceções forem inevitáveis.

Notas de Go

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

Alinhe tags com jobs de teste que usam -tags=integration.

Armadilhas

• Versões diferentes do golangci-lint localmente vs CI - Conjuntos de regras divergem. Correção: Fixe a versão na ação de CI e documente o comando de instalação para desenvolvedores.
• Diretivas nolint excessivamente amplas - //nolint:all esconde bugs futuros. Correção: Nomeie linters específicos e justifique em um comentário.
• Executar linters sem download de módulo - Falsos negativos ou erros de carregamento. Correção: go mod download antes do job de lint.
• Excluir arquivos de teste completamente - Testes escondem padrões de corrida (racey). Correção: Teste os testes também; use issues.exclude-rules apenas para caminhos conhecidos barulhentos.
• max-issues zero desde o primeiro dia - Equipes desabilitam a CI. Correção: Use new-from-rev ou modo de aviso temporário.
• Ignorar depreciações do staticcheck - Futuras versões do Go removem símbolos. Correção: Trate SA1019 (depreciado) como erros em bibliotecas.

Alternativas

FAQs

Relacionados

• Noções Básicas de Configuração de Ferramentas Go - instale staticcheck e golangci-lint
• gosec & nilaway para Segurança e Segurança Nil - analisadores de segurança e nil
• govulncheck para Vulnerabilidades de Dependência - escaneamento de CVE de dependência
• Escrevendo Analisadores go/analysis Personalizados - regras específicas da equipe
• Boas Práticas de Ferramentas de Análise e gopls - alinhamento de editor e CI

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