Enforcement de gofmt & goimports

gofmt e goimports são a camada de formatação que todo repositório Go deve automatizar.

Equipes os impõem em editores, hooks de pre-commit e CI para que as revisões se concentrem no comportamento em vez de espaços em branco.

Receita

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

# Formata todos os pacotes no local
gofmt -w .
goimports -local example.com/mycorp -w .
 
# CI: falha se algum arquivo for alterado
test -z "$(gofmt -l .)"
test -z "$(goimports -local example.com/mycorp -l .)"
 
# Simplificações opcionais
gofmt -s -w .

Quando usar isso:

• Bootstrapping de CONTRIBUTING.md para um novo serviço Go.
• Correção de ruído de PR "apenas formatação" em um monorepo movimentado.
• Onboarding de engenheiros de linguagens com formatadores configuráveis.
• Auditoria se o protobuf gerado ainda pertence a verificações de formato.

Exemplo de Trabalho

Layout do repositório:

example.com/widget/
  go.mod          # module example.com/mycorp/widget
  cmd/api/main.go
  internal/store/store.go

cmd/api/main.go antes do enforcement:

package main
 
import (
"fmt"
    "example.com/mycorp/widget/internal/store"
"net/http"
)
 
func main() {
store := store.New()
http.HandleFunc("/ok", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, store.Ping())
})
http.ListenAndServe(":8080", nil)
}

Imponha:

goimports -local example.com/mycorp -w ./cmd ./internal
gofmt -s -w ./cmd ./internal

Depois (o agrupamento de imports mostra o efeito de -local):

package main
 
import (
    "fmt"
    "net/http"
 
    "example.com/mycorp/widget/internal/store"
)
 
func main() {
    store := store.New()
    http.HandleFunc("/ok", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, store.Ping())
    })
    http.ListenAndServe(":8080", nil)
}

Trecho do GitHub Actions:

- name: Format check
  run: |
    test -z "$(gofmt -l .)"
    test -z "$(goimports -local example.com/mycorp -l .)"

O que isso demonstra:

• goimports corrige indentação e ordem de importação em uma única passagem.
• -local mantém módulos internos em um grupo de importação separado.
• CI falha em desvios sem reescrever as máquinas dos contribuidores.

Mergulho Profundo

Como Funciona

• gofmt analisa o código fonte Go e imprime espaçamento, indentação e quebras de linha canônicas.
• goimports chama gofmt após ajustar as declarações de importação.
• Ambos são determinísticos: sem substituições de .editorconfig para largura de tabulação.
• gopls pode aplicar as mesmas transformações ao salvar quando as configurações formatting.gofumpt ou goimports estão habilitadas.

Ordem do Grupo de Importação

Modos de Enforcement

Notas Go

# Verifica as versões das ferramentas para corresponder à CI
gofmt -V   # empacotado com a versão do go
go version -m $(which goimports) | head -1

Fixe a pseudo-versão golang.org/x/tools em tools.go para go install reproduzível de goimports entre laptops e agentes.

Flags que Valem a Pena Saber

Armadilhas

• Verificar gofmt, mas editar com goimports - Contribuidores passam localmente, mas a CI falha no agrupamento de imports. Correção: Padronize em goimports em hooks e CI.
• Esquecer -local na CI - Imports internos se misturam com caminhos de terceiros. Correção: Passe os mesmos prefixos -local em docs, hooks e fluxos de trabalho.
• Formatação de protobuf gerado - Grandes diffs em regen lutam contra os proprietários do código. Correção: Exclua *.pb.go dos caminhos de gofmt -l ou execute o formato como parte da geração de código.
• Versões Go misturadas em monorepo - A saída do gofmt raramente difere, mas o comportamento do goimports pode mudar com a versão do x/tools. Correção: Fixe ferramentas via tools.go e go install na CI.
• Revisar patches não formatados - Diffs escondem a lógica no ruído de espaços em branco. Correção: Exija formato antes de abrir PR (make fmt target).
• Usar go fmt como verificação - go fmt sempre reescreve arquivos; não é um padrão de CI apenas de listagem. Correção: Use gofmt -l ou um job de linting dedicado.

Alternativas

FAQs

Relacionado

• Qualidade de Código Go: Opinião por Design - por que o formato é inegociável
• Noções Básicas de Qualidade de Código - introdução executável a formato e vet
• Hooks de Pre-commit e Listas de Verificação de Revisão - fiação de hooks
• Configuração do golangci-lint - linter gofmt dentro do golangci-lint
• Padrões de Codificação e Convenções de Documentação para Equipes - padrões mais amplos da equipe

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