padrões-golang

Padrões de Desenvolvimento em Go

Padrões idiomáticos e melhores práticas em Go para construir aplicações robustas, eficientes e de fácil manutenção.

Quando Ativar

• Escrevendo novo código Go
• Revisando código Go
• Refatorando código Go existente
• Projetando pacotes/módulos Go

Princípios Fundamentais

1. Simplicidade e Clareza

Go favorece a simplicidade em vez de engenhosidade. O código deve ser óbvio e fácil de ler.

// Bom: Claro e direto
func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("get user %s: %w", id, err)
    }
    return user, nil
}

// Ruim: Excessivamente engenhoso
func GetUser(id string) (*User, error) {
    return func() (*User, error) {
        if u, e := db.FindUser(id); e == nil {
            return u, nil
        } else {
            return nil, e
        }
    }()
}

2. Torne o Valor Zero Útil

Projete tipos de forma que seu valor zero seja imediatamente utilizável, sem inicialização.

// Bom: Valor zero é útil
type Counter struct {
    mu    sync.Mutex
    count int // valor zero é 0, pronto para usar
}

func (c *Counter) Inc() {
    c.mu.Lock()
    c.count++
    c.mu.Unlock()
}

// Bom: bytes.Buffer funciona com valor zero
var buf bytes.Buffer
buf.WriteString("hello")

// Ruim: Requer inicialização
type BadCounter struct {
    counts map[string]int // mapa nil causará pânico
}

3. Aceite Interfaces, Retorne Structs

Funções devem aceitar parâmetros de interface e retornar tipos concretos.

// Bom: Aceita interface, retorna tipo concreto
func ProcessData(r io.Reader) (*Result, error) {
    data, err := io.ReadAll(r)
    if err != nil {
        return nil, err
    }
    return &Result{Data: data}, nil
}

// Ruim: Retorna interface (esconde detalhes de implementação desnecessariamente)
func ProcessData(r io.Reader) (io.Reader, error) {
    // ...
}

Padrões de Tratamento de Erros

Encapsulamento de Erros com Contexto

// Bom: Encapsula erros com contexto
func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("load config %s: %w", path, err)
    }

    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("parse config %s: %w", path, err)
    }

    return &cfg, nil
}

Tipos de Erro Personalizados

// Define erros específicos do domínio
type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
}

// Erros sentinela para casos comuns
var (
    ErrNotFound     = errors.New("resource not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrInvalidInput = errors.New("invalid input")
)

Verificação de Erros com errors.Is e errors.As

func HandleError(err error) {
    // Verifica erro específico
    if errors.Is(err, sql.ErrNoRows) {
        log.Println("No records found")
        return
    }

    // Verifica tipo de erro
    var validationErr *ValidationError
    if errors.As(err, &validationErr) {
        log.Printf("Validation error on field %s: %s",
            validationErr.Field, validationErr.Message)
        return
    }

    // Erro desconhecido
    log.Printf("Unexpected error: %v", err)
}

Nunca Ignore Erros

// Ruim: Ignorando erro com identificador em branco
result, _ := doSomething()

// Bom: Trata ou documenta explicitamente por que é seguro ignorar
result, err := doSomething()
if err != nil {
    return err
}

// Aceitável: Quando o erro realmente não importa (raro)
_ = writer.Close() // Limpeza de melhor esforço, erro registrado em outro lugar

Padrões de Concorrência

Pool de Workers

func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
    var wg sync.WaitGroup

    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- process(job)
            }
        }()
    }

    wg.Wait()
    close(results)
}

Contexto para Cancelamento e Timeouts

func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, fmt.Errorf("create request: %w", err)
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("fetch %s: %w", url, err)
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

Desligamento Gracioso

func GracefulShutdown(server *http.Server) {
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

    <-quit
    log.Println("Shutting down server...")

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := server.Shutdown(ctx); err != nil {
        log.Fatalf("Server forced to shutdown: %v", err)
    }

    log.Println("Server exited")
}

errgroup para Goroutines Coordenadas

import "golang.org/x/sync/errgroup"

func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
    g, ctx := errgroup.WithContext(ctx)
    results := make([][]byte, len(urls))

    for i, url := range urls {
        i, url := i, url // Captura variáveis do loop
        g.Go(func() error {
            data, err := FetchWithTimeout(ctx, url)
            if err != nil {
                return err
            }
            results[i] = data
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

Evitando Vazamentos de Goroutines

// Ruim: Vazamento de goroutine se o contexto for cancelado
func leakyFetch(ctx context.Context, url string) <-chan []byte {
    ch := make(chan []byte)
    go func() {
        data, _ := fetch(url)
        ch <- data // Bloqueia para sempre se não houver receptor
    }()
    return ch
}

// Bom: Lida corretamente com cancelamento
func safeFetch(ctx context.Context, url string) <-chan []byte {
    ch := make(chan []byte, 1) // Canal com buffer
    go func() {
        data, err := fetch(url)
        if err != nil {
            return
        }
        select {
        case ch <- data:
        case <-ctx.Done():
        }
    }()
    return ch
}

Design de Interfaces

Interfaces Pequenas e Focadas

// Bom: Interfaces de método único
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

// Componha interfaces conforme necessário
type ReadWriteCloser interface {
    Reader
    Writer
    Closer
}

Defina Interfaces Onde São Usadas

// No pacote consumidor, não no provedor
package service

// UserStore define o que este serviço precisa
type UserStore interface {
    GetUser(id string) (*User, error)
    SaveUser(user *User) error
}

type Service struct {
    store UserStore
}

// A implementação concreta pode estar em outro pacote
// Ela não precisa conhecer esta interface

Comportamento Opcional com Type Assertions

type Flusher interface {
    Flush() error
}

func WriteAndFlush(w io.Writer, data []byte) error {
    if _, err := w.Write(data); err != nil {
        return err
    }

    // Libere se suportado
    if f, ok := w.(Flusher); ok {
        return f.Flush()
    }
    return nil
}

Organização de Pacotes

Estrutura de Projeto Padrão

myproject/
├── cmd/
│   └── myapp/
│       └── main.go           # Ponto de entrada
├── internal/
│   ├── handler/              # Handlers HTTP
│   ├── service/              # Lógica de negócios
│   ├── repository/           # Acesso a dados
│   └── config/               # Configuração
├── pkg/
│   └── client/               # Cliente de API pública
├── api/
│   └── v1/                   # Definições de API (proto, OpenAPI)
├── testdata/                 # Fixtures de teste
├── go.mod
├── go.sum
└── Makefile

Nomenclatura de Pacotes

// Bom: Curto, minúsculo, sem sublinhados
package http
package json
package user

// Ruim: Verboso, maiúsculo/minúsculo misturado ou redundante
package httpHandler
package json_parser
package userService // Sufixo 'Service' redundante

Evite Estado no Nível do Pacote

// Ruim: Estado global mutável
var db *sql.DB

func init() {
    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
}

// Bom: Injeção de dependência
type Server struct {
    db *sql.DB
}

func NewServer(db *sql.DB) *Server {
    return &Server{db: db}
}

Design de Structs

Padrão de Opções Funcionais

type Server struct {
    addr    string
    timeout time.Duration
    logger  *log.Logger
}

type Option func(*Server)

func WithTimeout(d time.Duration) Option {
    return func(s *Server) {
        s.timeout = d
    }
}

func WithLogger(l *log.Logger) Option {
    return func(s *Server) {
        s.logger = l
    }
}

func NewServer(addr string, opts ...Option) *Server {
    s := &Server{
        addr:    addr,
        timeout: 30 * time.Second, // padrão
        logger:  log.Default(),    // padrão
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// Uso
server := NewServer(":8080",
    WithTimeout(60*time.Second),
    WithLogger(customLogger),
)

Embedding para Composição

type Logger struct {
    prefix string
}

func (l *Logger) Log(msg string) {
    fmt.Printf("[%s] %s\n", l.prefix, msg)
}

type Server struct {
    *Logger // Embedding - Server ganha método Log
    addr    string
}

func NewServer(addr string) *Server {
    return &Server{
        Logger: &Logger{prefix: "SERVER"},
        addr:   addr,
    }
}

// Uso
s := NewServer(":8080")
s.Log("Starting...") // Chama Logger.Log embutido

Memória e Desempenho

Pré-aloque Slices Quando o Tamanho é Conhecido

// Ruim: Cresce o slice várias vezes
func processItems(items []Item) []Result {
    var results []Result
    for _, item := range items {
        results = append(results, process(item))
    }
    return results
}

// Bom: Alocação única
func processItems(items []Item) []Result {
    results := make([]Result, 0, len(items))
    for _, item := range items {
        results = append(results, process(item))
    }
    return results
}

Use sync.Pool para Alocações Frequentes

var bufferPool = sync.Pool{
    New: func() interface{} {
        return new(bytes.Buffer)
    },
}

func ProcessRequest(data []byte) []byte {
    buf := bufferPool.Get().(*bytes.Buffer)
    defer func() {
        buf.Reset()
        bufferPool.Put(buf)
    }()

    buf.Write(data)
    // Processa...
    return buf.Bytes()
}

Evite Concatenação de Strings em Loops

// Ruim: Cria muitas alocações de string
func join(parts []string) string {
    var result string
    for _, p := range parts {
        result += p + ","
    }
    return result
}

// Bom: Alocação única com strings.Builder
func join(parts []string) string {
    var sb strings.Builder
    for i, p := range parts {
        if i > 0 {
            sb.WriteString(",")
        }
        sb.WriteString(p)
    }
    return sb.String()
}

// Melhor: Use a biblioteca padrão
func join(parts []string) string {
    return strings.Join(parts, ",")
}

Integração com Ferramentas Go

Comandos Essenciais

# Compilar e executar
go build ./...
go run ./cmd/myapp

# Testes
go test ./...
go test -race ./...
go test -cover ./...

# Análise estática
go vet ./...
staticcheck ./...
golangci-lint run

# Gerenciamento de módulos
go mod tidy
go mod verify

# Formatação
gofmt -w .
goimports -w .

Configuração Recomendada de Linter (.golangci.yml)

linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gofmt
    - goimports
    - misspell
    - unconvert
    - unparam

linters-settings:
  errcheck:
    check-type-assertions: true
  govet:
    enable:
      - shadow

issues:
  exclude-use-default: false

Referência Rápida: Expressões Idiomáticas em Go

Expressão	Descrição
Aceite interfaces, retorne structs	Funções aceitam parâmetros de interface, retornam tipos concretos
Erros são valores	Trate erros como valores de primeira classe, não exceções
Não se comunique compartilhando memória	Use canais para coordenação entre goroutines
Torne o valor zero útil	Tipos devem funcionar sem inicialização explícita
Um pouco de cópia é melhor que um pouco de dependência	Evite dependências externas desnecessárias
Claro é melhor que engenhoso	Priorize legibilidade em vez de engenhosidade
gofmt não é favorito de ninguém, mas é amigo de todos	Sempre formate com gofmt/goimports
Retorne cedo	Trate erros primeiro, mantenha o caminho feliz sem indentação

Anti-Padrões a Evitar

// Ruim: Retornos nus em funções longas
func process() (result int, err error) {
    // ... 50 linhas ...
    return // O que está sendo retornado?
}

// Ruim: Usando panic para fluxo de controle
func GetUser(id string) *User {
    user, err := db.Find(id)
    if err != nil {
        panic(err) // Não faça isso
    }
    return user
}

// Ruim: Passando contexto em struct
type Request struct {
    ctx context.Context // Contexto deve ser o primeiro parâmetro
    ID  string
}

// Bom: Contexto como primeiro parâmetro
func ProcessRequest(ctx context.Context, id string) error {
    // ...
}

// Ruim: Misturando receptores de valor e ponteiro
type Counter struct{ n int }
func (c Counter) Value() int { return c.n }    // Receptor de valor
func (c *Counter) Increment() { c.n++ }        // Receptor de ponteiro
// Escolha um estilo e seja consistente

Lembre-se: O código Go deve ser monótono da melhor forma possível - previsível, consistente e fácil de entender. Em caso de dúvida, mantenha simples.