Simplicidade como uma Restrição Deliberada no Design de APIs

A restrição da linguagem Go impulsiona as APIs de bibliotecas e serviços para superfícies pequenas, dependências explícitas e comportamento previsível.

Isso não é uma preferência de estilo - é como sistemas Go de manutenção sobrevivem a anos de rotatividade de pessoal e atualizações de dependência.

Resumo

Go favorece APIs "sem graça": poucos construtores, interfaces estreitas, erros explícitos e pacotes que fazem uma única tarefa.

Essa restrição acelera revisões, encolhe matrizes de teste e mantém atualizações compatíveis com a promessa Go 1.

Esta página mostra como projetar limites de pacotes e HTTP que correspondam à linguagem em vez de lutar contra ela.

Quando usar isso: Você está publicando uma biblioteca interna compartilhada, estabilizando um módulo público ou refatorando um "pacote deus" antes de um grande aumento de versão.

Receita

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

// Interface do lado do consumidor - um método, definido onde é usado.
type ObjectStore interface {
    Put(ctx context.Context, key string, body io.Reader) error
}
 
// Construtor retorna o tipo concreto; mantenha as opções funcionais.
type S3Store struct { /* ... */ }
 
func NewS3Store(cfg Config) (*S3Store, error) { /* valida cfg */ return &S3Store{}, nil }
 
// Função aceita interface, documenta erros.
func UploadReport(ctx context.Context, store ObjectStore, r io.Reader) error {
    if err := store.Put(ctx, "report.pdf", r); err != nil {
        return fmt.Errorf("upload report: %w", err)
    }
    return nil
}

Quando usar isso:

• Um pacote exporta mais de três construtores ou uma struct Config com 20 campos.
• Chamadores mockam interfaces que exigem stubbing de métodos não utilizados.
• Manipuladores HTTP acessam singletons globais em vez de aceitar dependências.
• Strings de erro são o único contrato entre serviços.

Exemplo de Trabalho

package checkout
 
import (
    "context"
    "errors"
    "fmt"
    "time"
)
 
// Erros de domínio são sentinelas de nível de pacote - estáveis para errors.Is.
var ErrInsufficientFunds = errors.New("checkout: insufficient funds")
 
type PaymentGateway interface {
    Charge(ctx context.Context, customerID string, cents int64) (chargeID string, err error)
}
 
type Service struct {
    gw  PaymentGateway
    now func() time.Time
}
 
func New(gw PaymentGateway) *Service {
    return &Service{gw: gw, now: time.Now}
}
 
type Request struct {
    CustomerID string
    Cents      int64
}
 
func (s *Service) Pay(ctx context.Context, req Request) (string, error) {
    if req.Cents <= 0 {
        return "", fmt.Errorf("checkout: invalid amount %d", req.Cents)
    }
    id, err := s.gw.Charge(ctx, req.CustomerID, req.Cents)
    if err != nil {
        return "", fmt.Errorf("checkout: charge: %w", err)
    }
    return id, nil
}

O que isso demonstra:

• Interface pequena no consumidor (PaymentGateway) mantém os fakes com uma largura de um método.
• Struct de serviço concreta com New documenta as dependências necessárias sem um framework de DI.
• Erro sentinela mais o encapsulamento fornecem aos operadores classificação estável e cadeias depuráveis.
• Struct Request agrupa entradas em vez de aumentar a aridade da função.
• Injeção de relógio via campo now mostra como testar o tempo sem exportar globais.

Mergulho Profundo

Como Funciona

• Pacotes Go são a unidade de design de API; identificadores exportados começam com letra maiúscula e se tornam compromissos de compatibilidade.
• Interfaces são satisfeitas implicitamente - projete-as nos pontos de chamada para que os produtores não sejam forçados a declarações implements em boilerplate.
• Erros são valores; encapsular com %w vincula causas enquanto preserva verificações sentinela via errors.Is e verificações de tipo via errors.As.
• context.Context é o primeiro parâmetro para cancelamento e valores com escopo de solicitação em limites de I/O.

Regras de Superfície de API em Resumo

Limites HTTP e gRPC

Para gRPC, prefira mensagens protobuf que espelhem substantivos de domínio, não todos os DTOs internos.

Mapeie erros de domínio para codes.InvalidArgument, codes.NotFound e codes.Internal em um único local.

Notas Go

// Opção funcional - escala sem explosão de Config.
type Option func(*Server)
 
func WithTimeout(d time.Duration) Option {
    return func(s *Server) { s.timeout = d }
}
 
func NewServer(opts ...Option) *Server {
    s := &Server{timeout: 30 * time.Second}
    for _, opt := range opts {
        opt(s)
    }
    return s
}

• Opções são idiomáticas quando os padrões são sensatos e as substituições são incomuns.
• Campos não exportados mantêm invariantes dentro do pacote.
• Documente quais opções são seguras para chamar após Start - mutar servidores em execução é um "pé-de-cabra" comum.

Armadilhas

• Interfaces exportadas crescem sem limites - cada novo método quebra todos os mocks. Correção: dividir interfaces ou mantê-las não exportadas dentro do pacote que precisa de fakes.
• Structs Config gigantes - os chamadores não conhecem os campos necessários; valores zero configuram silenciosamente de forma incorreta. Correção: validar em New, retornar erro, fornecer padrões apenas para botões seguros.
• Vazamento de *sql.DB por todas as camadas - acopla o domínio ao armazenamento. Correção: interface de repositório com tipos de domínio na borda do serviço.
• Erros tipados por string entre serviços - alertas se tornam arqueologia de regex. Correção: documentar erros sentinela e mapear para códigos HTTP/gRPC centralmente.
• Pacotes de abstração prematuros - internal/platform/core sem chamadores. Correção: esperar pelo segundo consumidor antes de extrair.
• Contexto em structs - armazena cancelamento com escopo incorreto. Correção: passar context.Context por método, nunca salvá-lo em campos.
• Quebra de alterações sem versão principal - módulos usam caminhos de importação (/v2) para mudanças de API incompatíveis. Correção: planejar v2 ao remover ou renomear exportações.

Alternativas

FAQs

Relacionado

• Por que Go Existe - metas de simplicidade em nível de linguagem
• Noções Básicas de Filosofia Go - aceitar interfaces, retornar structs na prática
• Melhores Práticas de Filosofia Go - lista de verificação de idiomatismos para toda a equipe
• Quando Go é a Ferramenta Errada - quando não investir em polimento de API Go

Versões da 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).

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x1v1v3x1v1t1v1z1t20