Configuração do golangci-lint

Q: Como migro do golangci-lint v1 para v2?

Execute golangci-lint migrate e leia o changelog do v2. Atualize a versão da ação de CI e o esquema de configuração juntos.

Q: Os testes devem ser lintados?

Sim. Muitos bugs aparecem apenas em arquivos _test.go (testinggoroutine, errcheck em falhas).

Q: Como lintar apenas pacotes alterados na CI?

Use --new-from-rev=origin/main ou filtros de caminho no workflow para velocidade. Mantenha um job noturno de repositório completo para desvios.

Q: Posso impor um comprimento máximo de linha?

revive e lll (frequentemente desabilitado por ser barulhento) cobrem isso. A comunidade Go prefere legibilidade a limites de coluna rígidos; use revisão para linhas gritantes.

Q: Como os presets se comparam às listas de habilitação manuais?

Presets como standard agrupam conjuntos opinativos. Listas de habilitação explícitas são mais claras para auditoria e documentação de integração.

Q: O golangci-lint substitui o gofmt?

Ele pode executar linters gofmt e goimports. A maioria das equipes ainda aplica o formato separadamente por velocidade e clareza.

Q: Como baselinar problemas legados?

Use exclusões issues.new temporariamente ou corrija em um sprint dedicado. Evite exclude-rules permanentes sem proprietários.

golangci-lint executa vários analisadores Go por meio de um único arquivo de configuração e uma única CLI.

As equipes usam .golangci.yml para escolher linters, definir severidade, excluir árvores geradas e manter as execuções locais alinhadas com a CI.

Receita

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

# Instala a versão fixada (corresponde à CI)
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.6
 
# Inicializa a configuração interativamente
golangci-lint config verify
 
# Executa com a configuração do repositório
golangci-lint run ./...
 
# Corrige automaticamente o que for seguro
golangci-lint run --fix ./...

Quando usar isso:

go vet está limpo, mas a revisão ainda pega os mesmos problemas do staticcheck.
Integração de vários serviços a uma única política de linter da plataforma.
Ajuste de ruído de protobuf, mocks ou vendor/.
Divisão de trabalhos de lint por módulo em um monorepo go.work.

Exemplo de Trabalho

.golangci.yml inicial para um único módulo de serviço:

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 # barulhento para fmt.Fprintf para 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 ./...

Job 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: ./...

O que isso demonstra:

disable-all: true e depois enable explícito mantêm o conjunto intencional.
exclude-files ignora protobuf e mocks gerados.
Fixar a versão no Makefile, na ação e na documentação evita desvios de "funciona localmente".

Mergulho Profundo

Como Funciona

O golangci-lint carrega os pacotes uma vez e executa os linters habilitados em paralelo onde for seguro.
Cada linter envolve ferramentas upstream (staticcheck, gosec, revive, etc.).
As descobertas são mescladas em um único relatório com o prefixo do nome do linter (staticcheck, govet, ...).
A configuração pode residir na raiz do repositório; módulos filhos podem carregar substituições.

Progressão de Habilitação Recomendada

Estágio	Linters	Objetivo
1	govet, errcheck, gosimple, ineffassign, unused	Correção de linha de base
2	staticcheck	API mais profunda e código morto
3	revive, stylecheck	Nomenclatura e comentários consistentes
4	gosec, bodyclose	Segurança e vazamentos de recursos HTTP
5	plugins personalizados	APIs específicas da organização

Padrões de Monorepo

# Raiz: padrões compartilhados
run:
  relative-path-mode: gomod
 
issues:
  exclude-dirs:
    - vendor

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

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

Executando a partir da raiz do workspace:

golangci-lint run ./services/billing/...
golangci-lint run ./services/...   # todos os módulos com go.mod

Supressões

//nolint:gosec // G304: caminho validado pelo contrato do chamador; veja SEC-123
os.Open(userPath)

Prefira //nolint estreito com ticket em vez de expressões regulares amplas de exclude-rules.

Notas do Go

# Verifica a sintaxe da configuração
golangci-lint config verify
 
# Lista os linters habilitados
golangci-lint linters
 
# Depura um único linter
golangci-lint run --disable-all -E staticcheck ./...

Armadilhas

golangci-lint não fixado na CI - Novas versões habilitam linters por padrão. Correção: Fixe a versão na ação e documente o processo de atualização.
Lintando monorepo inteiro sem timeouts - Repositórios grandes consomem muita memória ou atingem o padrão de 1m. Correção: Defina run.timeout: 5m e particione por módulo na matriz de CI.
Excluindo muito com regex - Oculta bugs reais em internal/legacy. Correção: Exclusão com tempo limitado e ticket de refatoração.
Executando --fix cegamente na CI - A correção automática pode alterar a semântica para alguns linters. Correção: Execute --fix localmente ou em PRs de bot, não em commits principais silenciosos.
Versão do Go incompatível - Linters usam informações de tipo da diretiva go do módulo. Correção: go-version da CI corresponde a go.mod.
Duplicação de vet via go vet e golangci-lint - Redundante, mas aceitável; remova go vet independente se govet enable-all estiver ativado.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`go vet` + CLI staticcheck	Dependências mínimas	Você quer um único relatório e exclusões compartilhadas
Multichecker `go/analysis` personalizado	Controle total, poucos linters	Você precisa de 20 linters da comunidade no primeiro dia
Política apenas de revisão	Nunca em escala	-
Lint `go:generate` por pacote	Incremental legado	Substituindo configuração centralizada

FAQs

Onde o .golangci.yml deve ficar?

Raiz do repositório para repositórios de módulo único.

Monorepos frequentemente usam padrões da raiz mais arquivos por módulo ao lado de go.mod.

Como migro do golangci-lint v1 para v2?

Execute golangci-lint migrate e leia o changelog do v2.

Atualize a versão da ação de CI e o esquema de configuração juntos.

Os testes devem ser lintados?

Sim.

Muitos bugs aparecem apenas em arquivos _test.go (testinggoroutine, errcheck em falhas).

Como lintar apenas pacotes alterados na CI?

Use --new-from-rev=origin/main ou filtros de caminho no workflow para velocidade.

Mantenha um job noturno de repositório completo para desvios.

E os workspaces go.work?

Execute o golangci-lint por diretório de módulo ou use padrões de caminho ./... a partir da raiz do workspace com relative-path-mode: gomod.

Posso impor um comprimento máximo de linha?

revive e lll (frequentemente desabilitado por ser barulhento) cobrem isso.

A comunidade Go prefere legibilidade a limites de coluna rígidos; use revisão para linhas gritantes.

Como os presets se comparam às listas de habilitação manuais?

Presets como standard agrupam conjuntos opinativos.

Listas de habilitação explícitas são mais claras para auditoria e documentação de integração.

O golangci-lint substitui o gofmt?

Ele pode executar linters gofmt e goimports.

A maioria das equipes ainda aplica o formato separadamente por velocidade e clareza.

Como baselinar problemas legados?

Use exclusões issues.new temporariamente ou corrija em um sprint dedicado.

Evite exclude-rules permanentes sem proprietários.

Valem a pena linters personalizados?

Após staticcheck e gosec esgotarem as regras genéricas.

Construa sobre go/analysis quando as APIs forem internas e estáveis.

Relacionados

go vet e Diagnósticos de Analisadores Comuns - mensagens do vet explicadas
staticcheck e golangci-lint na CI - padrões de integração de CI
Portões de Qualidade de CI: Lint, Test, Race, Vuln - posicionamento do job de lint
Hooks de Pré-commit e Listas de Verificação de Revisão - escopo de lint local
Boas Práticas de Lint e Qualidade de Código - regras de adoção

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - 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).

As equipes usam .golangci.yml para escolher linters, definir severidade, excluir árvores geradas e manter as execuções locais alinhadas com a CI.

Receita

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

# Instala a versão fixada (corresponde à CI)
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.6
 
# Inicializa a configuração interativamente
golangci-lint config verify
 
# Executa com a configuração do repositório
golangci-lint run ./...
 
# Corrige automaticamente o que for seguro
golangci-lint run --fix ./...

Quando usar isso:

go vet está limpo, mas a revisão ainda pega os mesmos problemas do staticcheck.
Integração de vários serviços a uma única política de linter da plataforma.
Ajuste de ruído de protobuf, mocks ou vendor/.
Divisão de trabalhos de lint por módulo em um monorepo go.work.

Exemplo de Trabalho

.golangci.yml inicial para um único módulo de serviço:

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 # barulhento para fmt.Fprintf para 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 ./...

Job 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: ./...

O que isso demonstra:

disable-all: true e depois enable explícito mantêm o conjunto intencional.
exclude-files ignora protobuf e mocks gerados.
Fixar a versão no Makefile, na ação e na documentação evita desvios de "funciona localmente".

Mergulho Profundo

Como Funciona

O golangci-lint carrega os pacotes uma vez e executa os linters habilitados em paralelo onde for seguro.
Cada linter envolve ferramentas upstream (staticcheck, gosec, revive, etc.).
As descobertas são mescladas em um único relatório com o prefixo do nome do linter (staticcheck, govet, ...).
A configuração pode residir na raiz do repositório; módulos filhos podem carregar substituições.

Progressão de Habilitação Recomendada

Estágio	Linters	Objetivo
1	govet, errcheck, gosimple, ineffassign, unused	Correção de linha de base
2	staticcheck	API mais profunda e código morto
3	revive, stylecheck	Nomenclatura e comentários consistentes
4	gosec, bodyclose	Segurança e vazamentos de recursos HTTP
5	plugins personalizados	APIs específicas da organização

Padrões de Monorepo

# Raiz: padrões compartilhados
run:
  relative-path-mode: gomod
 
issues:
  exclude-dirs:
    - vendor

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

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

Executando a partir da raiz do workspace:

golangci-lint run ./services/billing/...
golangci-lint run ./services/...   # todos os módulos com go.mod

Supressões

//nolint:gosec // G304: caminho validado pelo contrato do chamador; veja SEC-123
os.Open(userPath)

Prefira //nolint estreito com ticket em vez de expressões regulares amplas de exclude-rules.

Notas do Go

# Verifica a sintaxe da configuração
golangci-lint config verify
 
# Lista os linters habilitados
golangci-lint linters
 
# Depura um único linter
golangci-lint run --disable-all -E staticcheck ./...

Armadilhas

golangci-lint não fixado na CI - Novas versões habilitam linters por padrão. Correção: Fixe a versão na ação e documente o processo de atualização.
Lintando monorepo inteiro sem timeouts - Repositórios grandes consomem muita memória ou atingem o padrão de 1m. Correção: Defina run.timeout: 5m e particione por módulo na matriz de CI.
Excluindo muito com regex - Oculta bugs reais em internal/legacy. Correção: Exclusão com tempo limitado e ticket de refatoração.
Executando --fix cegamente na CI - A correção automática pode alterar a semântica para alguns linters. Correção: Execute --fix localmente ou em PRs de bot, não em commits principais silenciosos.
Versão do Go incompatível - Linters usam informações de tipo da diretiva go do módulo. Correção: go-version da CI corresponde a go.mod.
Duplicação de vet via go vet e golangci-lint - Redundante, mas aceitável; remova go vet independente se govet enable-all estiver ativado.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`go vet` + CLI staticcheck	Dependências mínimas	Você quer um único relatório e exclusões compartilhadas
Multichecker `go/analysis` personalizado	Controle total, poucos linters	Você precisa de 20 linters da comunidade no primeiro dia
Política apenas de revisão	Nunca em escala	-
Lint `go:generate` por pacote	Incremental legado	Substituindo configuração centralizada

FAQs

Onde o .golangci.yml deve ficar?

Raiz do repositório para repositórios de módulo único.

Monorepos frequentemente usam padrões da raiz mais arquivos por módulo ao lado de go.mod.

Como migro do golangci-lint v1 para v2?

Execute golangci-lint migrate e leia o changelog do v2.

Atualize a versão da ação de CI e o esquema de configuração juntos.

Os testes devem ser lintados?

Sim.

Muitos bugs aparecem apenas em arquivos _test.go (testinggoroutine, errcheck em falhas).

Como lintar apenas pacotes alterados na CI?

Use --new-from-rev=origin/main ou filtros de caminho no workflow para velocidade.

Mantenha um job noturno de repositório completo para desvios.

E os workspaces go.work?

Execute o golangci-lint por diretório de módulo ou use padrões de caminho ./... a partir da raiz do workspace com relative-path-mode: gomod.

Posso impor um comprimento máximo de linha?

revive e lll (frequentemente desabilitado por ser barulhento) cobrem isso.

A comunidade Go prefere legibilidade a limites de coluna rígidos; use revisão para linhas gritantes.

Como os presets se comparam às listas de habilitação manuais?

Presets como standard agrupam conjuntos opinativos.

Listas de habilitação explícitas são mais claras para auditoria e documentação de integração.

O golangci-lint substitui o gofmt?

Ele pode executar linters gofmt e goimports.

A maioria das equipes ainda aplica o formato separadamente por velocidade e clareza.

Como baselinar problemas legados?

Use exclusões issues.new temporariamente ou corrija em um sprint dedicado.

Evite exclude-rules permanentes sem proprietários.

Valem a pena linters personalizados?

Após staticcheck e gosec esgotarem as regras genéricas.

Construa sobre go/analysis quando as APIs forem internas e estáveis.

Relacionados

go vet e Diagnósticos de Analisadores Comuns - mensagens do vet explicadas
staticcheck e golangci-lint na CI - padrões de integração de CI
Portões de Qualidade de CI: Lint, Test, Race, Vuln - posicionamento do job de lint
Hooks de Pré-commit e Listas de Verificação de Revisão - escopo de lint local
Boas Práticas de Lint e Qualidade de Código - regras de adoção

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - 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).

Configuração do golangci-lint

Buscar na documentação

Configuração do golangci-lint