Guia Rápido de Regras Go

10 exemplos para você começar com as regras do 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 rulesdemo && cd rulesdemo && go mod init example.com/rulesdemo.
Leia Effective Go uma vez, depois use esta página como um complemento executável.

Exemplos Básicos

1. gofmt é inegociável

A formatação canônica é a primeira regra que todo repositório Go compartilha.

gofmt -w .
test -z "$(gofmt -l .)" || echo "arquivos precisam de formatação"

package main
 
import "fmt"
 
func main() {fmt.Println("antes do gofmt")}

gofmt remove completamente o debate sobre formatação da revisão de código.
O CI deve falhar quando gofmt -l imprimir qualquer caminho.
Não há configuração de estilo por projeto para manter.

Relacionado: Effective Go como um Padrão Vivo - como a orientação oficial se sobrepõe às regras da equipe

2. Verifique todo retorno de erro

O Go trata erros como valores; ignorá-los viola os idiomas principais.

package main
 
import (
    "fmt"
    "os"
)
 
func main() {
    f, err := os.Open("config.yaml")
    if err != nil {
        fmt.Fprintf(os.Stderr, "abrir config: %v\n", err)
        os.Exit(1)
    }
    defer f.Close()
}

Cada err de uma chamada de função precisa de um branch explícito.
Bibliotecas retornam erros; main decide se deve registrar, envolver ou sair.
_ descarta apenas quando você aceita deliberadamente a perda de sinal.

Relacionado: Erros como Valores: A Filosofia de Erros do Go - por que erros não são exceções

3. Envolva erros com contexto

Adicione %w quando os chamadores precisarem de errors.Is ou errors.As.

package demo
 
import (
    "errors"
    "fmt"
    "io"
)
 
var ErrNotFound = errors.New("demo: não encontrado")
 
func Load(r io.Reader) error {
    if r == nil {
        return fmt.Errorf("load: %w", ErrNotFound)
    }
    return nil
}

Envolva nas fronteiras onde você adiciona contexto de operação (load, fetch user).
Sentinelas permanecem estáveis; mensagens envolvidas podem incluir IDs.
Não envolva puramente para mudar a redação sem novas informações.

Relacionado: Envolvimento de Erros com %w e errors.As - profundidade e inspeção do envolvimento

4. context.Context como o primeiro parâmetro

Funções de IO e RPC aceitam cancelamento e prazos via contexto.

package demo
 
import (
    "context"
    "time"
)
 
func Fetch(ctx context.Context, id string) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    // ... use ctx em chamadas de saída
    return nil
}

Nomeie o parâmetro ctx; coloque-o primeiro na assinatura.
Passe ctx pela pilha; não o armazene em structs.
context.Background() pertence a main, testes e manipuladores de nível superior.

Relacionado: Checklist de Regras de Concorrência - regras de cancelamento e propriedade

5. Aceite interfaces, retorne tipos concretos

Mantenha os parâmetros de função flexíveis; mantenha os tipos de retorno específicos.

package demo
 
import "io"
 
type Store struct{}
 
func (s *Store) Save(w io.Writer, data []byte) (int, error) {
    return w.Write(data)
}
 
func NewStore() *Store { return &Store{} }

Os chamadores passam io.Writer, io.Reader ou pequenas interfaces de domínio.
Retornar *Store evita comportamentos surpreendentes por trás de interfaces sem nome.
Defina interfaces ao lado dos consumidores, não ao lado dos produtores.

Relacionado: Regras de Design de API para Bibliotecas Go - regras de nomenclatura e superfície

6. Documente símbolos exportados

Identificadores exportados são um contrato de compatibilidade.

// Pacote demo mostra godoc mínimo em exports.
package demo
 
// Greeter formata uma saudação para o nome.
// Retorna uma string vazia quando o nome está em branco.
func Greeter(name string) string {
    if name == "" {
        return ""
    }
    return "hello, " + name
}

Godoc em pacotes e funcs/tipos exportados é obrigatório para bibliotecas.
Comece os comentários com o nome do símbolo ("Greeter ...").
Exemplos em example_test.go aparecem em pkg.go.dev.

Relacionado: Checklist de Regras de Effective Go - lista completa de idiomas

7. Execute go vet antes da revisão

Vet pega erros que o compilador permite.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "texto") // vet: incompatibilidade de verbo de formato
}

Adicione vet ao CI junto com os testes.
Novas versões do Go às vezes adicionam analisadores vet; leia as notas de lançamento.
Vet complementa os linters; não é um substituto para testes.

Relacionado: Noções Básicas de Qualidade de Código - formato, vet e hooks

Exemplos Intermediários

8. Testes orientados por tabela para exemplos de regras

Codifique o comportamento da regra como dados para que os revisores vejam os casos claramente.

package demo
 
import "testing"
 
func TestGreeter(t *testing.T) {
    tests := []struct {
        name string
        in   string
        want string
    }{
        {"vazio", "", ""},
        {"alice", "alice", "hello, alice"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := Greeter(tt.in); got != tt.want {
                t.Fatalf("got %q want %q", got, tt.want)
            }
        })
    }
}

Testes de tabela documentam o comportamento esperado melhor do que regras em prosa.
Use nomes t.Run que leiam como itens de checklist.
Emparelhe com -race quando os testes tocarem em goroutines.

Relacionado: Testes Orientados por Tabela e Subtestes - regras de estrutura de teste

9. internal/ para limites de módulo

Oculte pacotes de implementação que os consumidores não devem importar.

rulesdemo/
  go.mod
  demo/
    public.go
  internal/
    storage/
      storage.go

// a raiz do módulo importa apenas pacotes públicos; internal é imposto pelo compilador.
import "example.com/rulesdemo/internal/storage" // falha fora do módulo

Caminhos internal/ são rejeitados pelo compilador entre limites de módulo.
A superfície da API pública permanece pequena; semver se aplica a pacotes exportados.
Prefira internal em vez de apenas documentação para "não importar".

Relacionado: Nomenclatura de Pacotes e Diretórios internal/ - regras de layout

10. Meça antes de aplicar regras de desempenho

Regras de otimização assumem evidências de profiling.

go test -bench=. -benchmem ./...
go test -cpuprofile=cpu.prof -bench=. ./...
go tool pprof -top cpu.prof

Padrão para código claro; otimize os caminhos quentes mostrados nos perfis.
Registre benchmarks de linha de base ao reivindicar uma aceleração.
Leia Regras de Desempenho: Quando Otimizar antes de ajustar GC ou alocações.

Relacionado: Regras de Desempenho: Quando Otimizar - fluxo de trabalho de medição primeiro

Links Externos Relacionados

A Tour of Go - Introdução interativa oficial ao Go.
Effective Go - Guia oficial para escrever Go claro e idiomático.
Tutoriais Go (Oficial) - Tutoriais oficiais em várias partes.
Get Programming with Go (Manning) - Nathan Youngman & Roger Peppé.
The Go Programming Language (ebook) - Donovan & Kernighan.

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - 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 rulesdemo && cd rulesdemo && go mod init example.com/rulesdemo.
Leia Effective Go uma vez, depois use esta página como um complemento executável.

Exemplos Básicos

1. gofmt é inegociável

A formatação canônica é a primeira regra que todo repositório Go compartilha.

gofmt -w .
test -z "$(gofmt -l .)" || echo "arquivos precisam de formatação"

package main
 
import "fmt"
 
func main() {fmt.Println("antes do gofmt")}

gofmt remove completamente o debate sobre formatação da revisão de código.
O CI deve falhar quando gofmt -l imprimir qualquer caminho.
Não há configuração de estilo por projeto para manter.

Relacionado: Effective Go como um Padrão Vivo - como a orientação oficial se sobrepõe às regras da equipe

2. Verifique todo retorno de erro

O Go trata erros como valores; ignorá-los viola os idiomas principais.

package main
 
import (
    "fmt"
    "os"
)
 
func main() {
    f, err := os.Open("config.yaml")
    if err != nil {
        fmt.Fprintf(os.Stderr, "abrir config: %v\n", err)
        os.Exit(1)
    }
    defer f.Close()
}

Cada err de uma chamada de função precisa de um branch explícito.
Bibliotecas retornam erros; main decide se deve registrar, envolver ou sair.
_ descarta apenas quando você aceita deliberadamente a perda de sinal.

Relacionado: Erros como Valores: A Filosofia de Erros do Go - por que erros não são exceções

3. Envolva erros com contexto

Adicione %w quando os chamadores precisarem de errors.Is ou errors.As.

package demo
 
import (
    "errors"
    "fmt"
    "io"
)
 
var ErrNotFound = errors.New("demo: não encontrado")
 
func Load(r io.Reader) error {
    if r == nil {
        return fmt.Errorf("load: %w", ErrNotFound)
    }
    return nil
}

Envolva nas fronteiras onde você adiciona contexto de operação (load, fetch user).
Sentinelas permanecem estáveis; mensagens envolvidas podem incluir IDs.
Não envolva puramente para mudar a redação sem novas informações.

Relacionado: Envolvimento de Erros com %w e errors.As - profundidade e inspeção do envolvimento

4. context.Context como o primeiro parâmetro

Funções de IO e RPC aceitam cancelamento e prazos via contexto.

package demo
 
import (
    "context"
    "time"
)
 
func Fetch(ctx context.Context, id string) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    // ... use ctx em chamadas de saída
    return nil
}

Nomeie o parâmetro ctx; coloque-o primeiro na assinatura.
Passe ctx pela pilha; não o armazene em structs.
context.Background() pertence a main, testes e manipuladores de nível superior.

Relacionado: Checklist de Regras de Concorrência - regras de cancelamento e propriedade

5. Aceite interfaces, retorne tipos concretos

Mantenha os parâmetros de função flexíveis; mantenha os tipos de retorno específicos.

package demo
 
import "io"
 
type Store struct{}
 
func (s *Store) Save(w io.Writer, data []byte) (int, error) {
    return w.Write(data)
}
 
func NewStore() *Store { return &Store{} }

Os chamadores passam io.Writer, io.Reader ou pequenas interfaces de domínio.
Retornar *Store evita comportamentos surpreendentes por trás de interfaces sem nome.
Defina interfaces ao lado dos consumidores, não ao lado dos produtores.

Relacionado: Regras de Design de API para Bibliotecas Go - regras de nomenclatura e superfície

6. Documente símbolos exportados

Identificadores exportados são um contrato de compatibilidade.

// Pacote demo mostra godoc mínimo em exports.
package demo
 
// Greeter formata uma saudação para o nome.
// Retorna uma string vazia quando o nome está em branco.
func Greeter(name string) string {
    if name == "" {
        return ""
    }
    return "hello, " + name
}

Godoc em pacotes e funcs/tipos exportados é obrigatório para bibliotecas.
Comece os comentários com o nome do símbolo ("Greeter ...").
Exemplos em example_test.go aparecem em pkg.go.dev.

Relacionado: Checklist de Regras de Effective Go - lista completa de idiomas

7. Execute go vet antes da revisão

Vet pega erros que o compilador permite.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "texto") // vet: incompatibilidade de verbo de formato
}

Adicione vet ao CI junto com os testes.
Novas versões do Go às vezes adicionam analisadores vet; leia as notas de lançamento.
Vet complementa os linters; não é um substituto para testes.

Relacionado: Noções Básicas de Qualidade de Código - formato, vet e hooks

Exemplos Intermediários

8. Testes orientados por tabela para exemplos de regras

Codifique o comportamento da regra como dados para que os revisores vejam os casos claramente.

package demo
 
import "testing"
 
func TestGreeter(t *testing.T) {
    tests := []struct {
        name string
        in   string
        want string
    }{
        {"vazio", "", ""},
        {"alice", "alice", "hello, alice"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := Greeter(tt.in); got != tt.want {
                t.Fatalf("got %q want %q", got, tt.want)
            }
        })
    }
}

Testes de tabela documentam o comportamento esperado melhor do que regras em prosa.
Use nomes t.Run que leiam como itens de checklist.
Emparelhe com -race quando os testes tocarem em goroutines.

Relacionado: Testes Orientados por Tabela e Subtestes - regras de estrutura de teste

9. internal/ para limites de módulo

Oculte pacotes de implementação que os consumidores não devem importar.

rulesdemo/
  go.mod
  demo/
    public.go
  internal/
    storage/
      storage.go

// a raiz do módulo importa apenas pacotes públicos; internal é imposto pelo compilador.
import "example.com/rulesdemo/internal/storage" // falha fora do módulo

Caminhos internal/ são rejeitados pelo compilador entre limites de módulo.
A superfície da API pública permanece pequena; semver se aplica a pacotes exportados.
Prefira internal em vez de apenas documentação para "não importar".

Relacionado: Nomenclatura de Pacotes e Diretórios internal/ - regras de layout

10. Meça antes de aplicar regras de desempenho

Regras de otimização assumem evidências de profiling.

go test -bench=. -benchmem ./...
go test -cpuprofile=cpu.prof -bench=. ./...
go tool pprof -top cpu.prof

Padrão para código claro; otimize os caminhos quentes mostrados nos perfis.
Registre benchmarks de linha de base ao reivindicar uma aceleração.
Leia Regras de Desempenho: Quando Otimizar antes de ajustar GC ou alocações.

Relacionado: Regras de Desempenho: Quando Otimizar - fluxo de trabalho de medição primeiro

Links Externos Relacionados

A Tour of Go - Introdução interativa oficial ao Go.
Effective Go - Guia oficial para escrever Go claro e idiomático.
Tutoriais Go (Oficial) - Tutoriais oficiais em várias partes.
Get Programming with Go (Manning) - Nathan Youngman & Roger Peppé.
The Go Programming Language (ebook) - Donovan & Kernighan.

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

Guia Rápido de Regras Go

Buscar na documentação

Guia Rápido de Regras Go