Noções Básicas de Qualidade de Código

10 exemplos para você começar com a qualidade de código Go - 7 básicos e 3 intermediários.

Pré-requisitos

Instale o Go 1.26.x ou posterior em go.dev/dl.
Crie um módulo: mkdir quality && cd quality && go mod init example.com/quality.
Instale os auxiliares: go install golang.org/x/tools/cmd/goimports@latest e go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest.

Exemplos Básicos

1. gofmt in-place

Reescreve um arquivo para a formatação Go canônica.

gofmt -w main.go

package main
 
import "fmt"
 
func main() {fmt.Println("hello")}

Após gofmt -w, o espaçamento e a indentação correspondem ao estilo da comunidade.

gofmt é determinístico: a mesma entrada sempre produz a mesma saída.
O CI frequentemente executa test -z "$(gofmt -l .)" para falhar em caso de desvio.
Não há configuração de formato em nível de projeto para manter.

Relacionado: Aplicação de gofmt & goimports - política de formatação da equipe

2. goimports para imports

Formata e corrige blocos de importação em uma única etapa.

goimports -w .

package main
 
import "fmt"
 
func main() {
    fmt.Println(time.Now()) // importação ausente antes do goimports
}

goimports adiciona importações ausentes da biblioteca padrão e remove as não utilizadas.
Use -local example.com/quality para agrupar os caminhos do seu módulo separadamente.
Editores frequentemente executam goimports ao salvar via gopls.

Relacionado: Aplicação de gofmt & goimports - agrupamento -local

3. go vet em todos os pacotes

Executa analisadores integrados em todo o módulo.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "not-a-number") // vet: incompatibilidade de formato Printf
}

vet relata problemas que o compilador aceita, mas que provavelmente são bugs.
Execute no CI em cada PR; zero descobertas deve ser o padrão.
Novas versões do Go podem adicionar verificações de vet - leia as notas de lançamento.

Relacionado: go vet & Diagnósticos Comuns de Analisadores - mensagens comuns

4. Portão de teste mínimo

A qualidade inclui o comportamento, não apenas verificações estáticas.

go test ./...

package add
 
func Sum(a, b int) int { return a + b }

package add_test
 
import "testing"
 
func TestSum(t *testing.T) {
    if got := add.Sum(2, 3); got != 5 {
        t.Fatalf("got %d", got)
    }
}

Os testes residem em arquivos *_test.go no mesmo pacote (ou no pacote externo _test).
go test compila testes com o detector de corrida quando você passa -race.
Falhas de teste devem bloquear o merge antes que debates sobre linters importem.

Relacionado: Portões de Qualidade de CI: Lint, Teste, Corrida, Vulnerabilidade - pipeline completo

5. Listar arquivos não formatados

Verifica a formatação sem escrever arquivos (amigável ao CI).

gofmt -l .

Saída vazia significa que todos os arquivos .go estão formatados.
Saída não vazia lista caminhos que precisam de gofmt -w.
Emparelhe com git diff --exit-code após a formatação em hooks pre-commit.

Relacionado: Hooks Pre-commit & Checklists de Revisão - automação local

6. Primeira execução do golangci-lint

Executa o pacote padrão de linters.

golangci-lint run ./...

A primeira execução baixa os binários dos analisadores; fixe a versão no CI para reprodutibilidade.
Comece com os linters padrão; ajuste .golangci.yml após o baseline estar verde.
Corrija problemas do tipo vet antes de perseguir pequenas questões de estilo.

Relacionado: Configuração do golangci-lint - padrões de arquivo de configuração

7. Alvo check do Makefile

Um comando para contribuidores.

.PHONY: check
check:
	gofmt -l . | tee /tmp/gofmt.out && test ! -s /tmp/gofmt.out
	go vet ./...
	go test ./...

make check

Documente make check no README e CONTRIBUTING.
Expanda com golangci-lint run quando a equipe estiver pronta.
Mantenha os alvos rápidos o suficiente para hooks pre-push (< 2 minutos em laptops).

Relacionado: Melhores Práticas de Linting & Qualidade de Código - ritmo de adoção

Exemplos Intermediários

8. Detector de corrida em testes

Detecta corridas de dados que vet não pega.

go test -race ./...

package counter
 
import "sync"
 
type Counter struct {
    mu sync.Mutex
    n  int
}
 
func (c *Counter) Inc() {
    c.mu.Lock()
    c.n++
    c.mu.Unlock()
}

-race torna os testes mais lentos e requer mais memória; execute no CI, não a cada salvamento.
Falhas de corrida incluem pilhas de goroutines - corrija adicionando sincronização.
Manipuladores HTTP compartilhando estado mutável sem locks são um gatilho comum.

Relacionado: Portões de Qualidade de CI: Lint, Teste, Corrida, Vulnerabilidade - quando exigir corrida

9. Verificação go mod tidy

Mantém os metadados do módulo consistentes.

go mod tidy
git diff --exit-code go.mod go.sum

Falha no CI quando as dependências divergem sem atualizações go.sum commitadas.
Execute após atualizações de dependência e antes de marcar lançamentos.
Emparelhe com govulncheck para verificação de segurança no grafo tidy.

Relacionado: govulncheck para Vulnerabilidades de Dependência - verificação de CVE

10. Script pre-commit simples

Bloqueia commits que falham em verificações rápidas.

#!/usr/bin/env bash
set -euo pipefail
gofmt -l . | grep . && { echo "run gofmt -w"; exit 1; } || true
go vet ./...
go test ./...

chmod +x scripts/pre-commit.sh
# Conecte com: ln -s ../../scripts/pre-commit.sh .git/hooks/pre-commit

Hooks detectam problemas antes do tempo de fila do CI.
Mantenha os hooks rápidos; adie golangci-lint para o CI se exceder ~60s localmente.
Documente a política de bypass (--no-verify) apenas para emergências.

Relacionado: Hooks Pre-commit & Checklists de Revisão - modelos de hook

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

Pré-requisitos

Instale o Go 1.26.x ou posterior em go.dev/dl.
Crie um módulo: mkdir quality && cd quality && go mod init example.com/quality.
Instale os auxiliares: go install golang.org/x/tools/cmd/goimports@latest e go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest.

Exemplos Básicos

1. gofmt in-place

Reescreve um arquivo para a formatação Go canônica.

gofmt -w main.go

package main
 
import "fmt"
 
func main() {fmt.Println("hello")}

Após gofmt -w, o espaçamento e a indentação correspondem ao estilo da comunidade.

gofmt é determinístico: a mesma entrada sempre produz a mesma saída.
O CI frequentemente executa test -z "$(gofmt -l .)" para falhar em caso de desvio.
Não há configuração de formato em nível de projeto para manter.

Relacionado: Aplicação de gofmt & goimports - política de formatação da equipe

2. goimports para imports

Formata e corrige blocos de importação em uma única etapa.

goimports -w .

package main
 
import "fmt"
 
func main() {
    fmt.Println(time.Now()) // importação ausente antes do goimports
}

goimports adiciona importações ausentes da biblioteca padrão e remove as não utilizadas.
Use -local example.com/quality para agrupar os caminhos do seu módulo separadamente.
Editores frequentemente executam goimports ao salvar via gopls.

Relacionado: Aplicação de gofmt & goimports - agrupamento -local

3. go vet em todos os pacotes

Executa analisadores integrados em todo o módulo.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "not-a-number") // vet: incompatibilidade de formato Printf
}

vet relata problemas que o compilador aceita, mas que provavelmente são bugs.
Execute no CI em cada PR; zero descobertas deve ser o padrão.
Novas versões do Go podem adicionar verificações de vet - leia as notas de lançamento.

Relacionado: go vet & Diagnósticos Comuns de Analisadores - mensagens comuns

4. Portão de teste mínimo

A qualidade inclui o comportamento, não apenas verificações estáticas.

go test ./...

package add
 
func Sum(a, b int) int { return a + b }

package add_test
 
import "testing"
 
func TestSum(t *testing.T) {
    if got := add.Sum(2, 3); got != 5 {
        t.Fatalf("got %d", got)
    }
}

Os testes residem em arquivos *_test.go no mesmo pacote (ou no pacote externo _test).
go test compila testes com o detector de corrida quando você passa -race.
Falhas de teste devem bloquear o merge antes que debates sobre linters importem.

Relacionado: Portões de Qualidade de CI: Lint, Teste, Corrida, Vulnerabilidade - pipeline completo

5. Listar arquivos não formatados

Verifica a formatação sem escrever arquivos (amigável ao CI).

gofmt -l .

Saída vazia significa que todos os arquivos .go estão formatados.
Saída não vazia lista caminhos que precisam de gofmt -w.
Emparelhe com git diff --exit-code após a formatação em hooks pre-commit.

Relacionado: Hooks Pre-commit & Checklists de Revisão - automação local

6. Primeira execução do golangci-lint

Executa o pacote padrão de linters.

golangci-lint run ./...

A primeira execução baixa os binários dos analisadores; fixe a versão no CI para reprodutibilidade.
Comece com os linters padrão; ajuste .golangci.yml após o baseline estar verde.
Corrija problemas do tipo vet antes de perseguir pequenas questões de estilo.

Relacionado: Configuração do golangci-lint - padrões de arquivo de configuração

7. Alvo check do Makefile

Um comando para contribuidores.

.PHONY: check
check:
	gofmt -l . | tee /tmp/gofmt.out && test ! -s /tmp/gofmt.out
	go vet ./...
	go test ./...

make check

Documente make check no README e CONTRIBUTING.
Expanda com golangci-lint run quando a equipe estiver pronta.
Mantenha os alvos rápidos o suficiente para hooks pre-push (< 2 minutos em laptops).

Relacionado: Melhores Práticas de Linting & Qualidade de Código - ritmo de adoção

Exemplos Intermediários

8. Detector de corrida em testes

Detecta corridas de dados que vet não pega.

go test -race ./...

package counter
 
import "sync"
 
type Counter struct {
    mu sync.Mutex
    n  int
}
 
func (c *Counter) Inc() {
    c.mu.Lock()
    c.n++
    c.mu.Unlock()
}

-race torna os testes mais lentos e requer mais memória; execute no CI, não a cada salvamento.
Falhas de corrida incluem pilhas de goroutines - corrija adicionando sincronização.
Manipuladores HTTP compartilhando estado mutável sem locks são um gatilho comum.

Relacionado: Portões de Qualidade de CI: Lint, Teste, Corrida, Vulnerabilidade - quando exigir corrida

9. Verificação go mod tidy

Mantém os metadados do módulo consistentes.

go mod tidy
git diff --exit-code go.mod go.sum

Falha no CI quando as dependências divergem sem atualizações go.sum commitadas.
Execute após atualizações de dependência e antes de marcar lançamentos.
Emparelhe com govulncheck para verificação de segurança no grafo tidy.

Relacionado: govulncheck para Vulnerabilidades de Dependência - verificação de CVE

10. Script pre-commit simples

Bloqueia commits que falham em verificações rápidas.

#!/usr/bin/env bash
set -euo pipefail
gofmt -l . | grep . && { echo "run gofmt -w"; exit 1; } || true
go vet ./...
go test ./...

chmod +x scripts/pre-commit.sh
# Conecte com: ln -s ../../scripts/pre-commit.sh .git/hooks/pre-commit

Hooks detectam problemas antes do tempo de fila do CI.
Mantenha os hooks rápidos; adie golangci-lint para o CI se exceder ~60s localmente.
Documente a política de bypass (--no-verify) apenas para emergências.

Relacionado: Hooks Pre-commit & Checklists de Revisão - modelos de hook

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

Noções Básicas de Qualidade de Código

Buscar na documentação

Noções Básicas de Qualidade de Código