Padrões Go
Medido: a fronteira atual e modelos pequenos de Claude já escrevem corretamente as mecânicas de concorrência comuns aqui (pool de workers, estágios de pipeline, fechamento de canal) em uma única tentativa, sem esta habilidade — um estudo controlado encontrou zero headroom de correção, 184/184 passando em ambos os braços (o
evals/RESULTS.md§2 do repositório). Recorra a esta habilidade para as escolhas de design — interfaces, fiação de dependências, modelagem de erros, layout de pacotes — como uma lista de verificação de revisão, ou ao conduzir modelos mais fracos; não porque um modelo atual travaria de outra forma.
Escopo: arquivos Go, go.mod e go.sum.
Origem: Derivado de Everything Claude Code (MIT, (c) 2026 Affaan Mustafa).
Esta habilidade fornece padrões Go abrangentes estendendo princípios de design comuns com expressões idiomáticas específicas de Go.
Opções Funcionais
Use o padrão de opções funcionais para configuração flexível de construtor:
type Option func(*Server)
func WithPort(port int) Option {
return func(s *Server) { s.port = port }
}
func NewServer(opts ...Option) *Server {
s := &Server{port: 8080}
for _, opt := range opts {
opt(s)
}
return s
}
Benefícios:
- Evolução de API compatível com versões anteriores
- Parâmetros opcionais com valores padrão
- Configuração autodocumentada
Interfaces Pequenas
Defina interfaces onde elas são usadas, não onde são implementadas.
Princípio: Aceite interfaces, retorne structs
// Bom: Interface pequena e focada definida no ponto de uso
type UserStore interface {
GetUser(id string) (*User, error)
}
func ProcessUser(store UserStore, id string) error {
user, err := store.GetUser(id)
// ...
}
Benefícios:
- Testes e mocks mais fáceis
- Acoplamento fraco
- Dependências claras
Injeção de Dependência
Use funções construtoras para injetar dependências:
func NewUserService(repo UserRepository, logger Logger) *UserService {
return &UserService{
repo: repo,
logger: logger,
}
}
Padrão:
- Funções construtoras (prefixo New*)
- Dependências explícitas como parâmetros
- Retorno de tipos concretos
- Valide dependências no construtor
Padrões de Concorrência
Pool de Workers
func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
var wg sync.WaitGroup
for i := 0; i < workers; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for job := range jobs {
results <- processJob(job)
}
}()
}
// Fecha results assim que todos os workers terminarem — em uma goroutine
// separada para que esta função retorne imediatamente e o chamador possa
// iterar sobre results enquanto os workers ainda estão produzindo. Um
// wg.Wait() inline aqui causaria deadlock: os workers bloqueiam ao enviar
// para results até que um leitor os esvazie, mas o leitor só executa depois
// que workerPool retorna.
go func() {
wg.Wait()
close(results)
}()
}
Propagação de Contexto
Sempre passe contexto como primeiro parâmetro:
func FetchUser(ctx context.Context, id string) (*User, error) {
// Verifique cancelamento de contexto
select {
case <-ctx.Done():
return nil, ctx.Err()
default:
}
// ... lógica de busca
}
Tratamento de Erros
Encapsulamento de Erros
if err != nil {
return fmt.Errorf("falha ao buscar usuário %s: %w", id, err)
}
Erros Personalizados
type ValidationError struct {
Field string
Msg string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("%s: %s", e.Field, e.Msg)
}
Erros Sentinela
var (
ErrNotFound = errors.New("não encontrado")
ErrInvalid = errors.New("entrada inválida")
)
// Verifique com errors.Is
if errors.Is(err, ErrNotFound) {
// trate não encontrado
}
Organização de Pacotes
Estrutura
projeto/
├── cmd/ # Aplicações principais
│ └── servidor/
│ └── main.go
├── internal/ # Código de aplicação privado
│ ├── dominio/ # Lógica de negócio
│ ├── handler/ # Handlers HTTP
│ └── repositorio/ # Acesso a dados
└── pkg/ # Bibliotecas públicas
Convenções de Nomenclatura
- Nomes de pacotes: minúsculo, palavra única
- Evite repetição:
user.Usernãouser.UserModel - Use
internal/para código privado - Mantenha o pacote
mainmínimo
Padrões de Teste
Testes Orientados por Tabelas
func TestValidate(t *testing.T) {
tests := []struct {
name string
input string
wantErr bool
}{
{"válido", "[email protected]", false},
{"inválido", "não-um-email", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := Validate(tt.input)
if (err != nil) != tt.wantErr {
t.Errorf("erro obtido %v, wantErr %v", err, tt.wantErr)
}
})
}
}
Helpers de Teste
// Importe o driver puramente Go: _ "modernc.org/sqlite" (registra como "sqlite").
// NÃO use "sqlite3" (mattn/go-sqlite3) — ele precisa de CGO e quebra builds
// estáticos CGO_ENABLED=0. O pacote greenfield-go-stack exige puramente Go/sem CGO.
func testDB(t *testing.T) *sql.DB {
t.Helper()
db, err := sql.Open("sqlite", ":memory:")
if err != nil {
t.Fatalf("falha ao abrir banco de teste: %v", err)
}
// Um banco ":memory:" é privado para uma única conexão, e database/sql
// é um pool preguiçoso: sem isso, cada conexão do pool obtém seu PRÓPRIO banco
// vazio, então uma tabela criada em uma conexão está faltando na próxima.
// Fixar o pool a uma conexão faz todo o teste compartilhar um banco em memória.
// RESSALVA: com uma única conexão, enquanto uma tx estiver aberta (db.Begin),
// essa tx mantém a única conexão — roteie TODO o trabalho através da tx até
// Commit/Rollback; um db.Query concorrente no pool bloquearia esperando por ela.
// Se um teste realmente precisa de múltiplas conexões ativas, use um DSN de cache
// compartilhado ("file:testdb?mode=memory&cache=shared") e mantenha >=1 conexão
// aberta para que o banco em memória não seja descartado.
db.SetMaxOpenConns(1)
t.Cleanup(func() { db.Close() })
return db
}
Quando Usar Esta Habilidade
- Projetar APIs e pacotes Go
- Implementar sistemas concorrentes
- Estruturar projetos Go
- Escrever código Go idiomático
- Refatorar bases de código Go