Regras de Design de API para Bibliotecas Go
Nomenclatura, retornos de erro, contexto como primeiro parâmetro e alterações que quebram a compatibilidade.
//
Busque em todas as páginas da documentação
Nomenclatura, retornos de erro, contexto como primeiro parâmetro e alterações que quebram a compatibilidade.
Referência densa para autores que publicam bibliotecas Go - revise antes de exportar novos símbolos ou marcar um lançamento.
go vet, verificações de API do staticcheck e tags semver.| Regra | Fazer | Evitar | Justificativa |
|---|---|---|---|
| Nome do pacote | Curto, minúsculo, sem underscores (httpclient) | common, util, misc | Legibilidade do caminho de importação |
| Nome exportado | CamelCase, sem repetição (user.UserID) | user.UserUserID | Clareza em pkg.go.dev |
| Getter | Name() em vez de GetName() | Estilo Java Get* em campos simples | Convenção Go |
| Nome da interface | Sufixo -er quando um método (Reader) | IReader | Interfaces idiomáticas |
| Acrônimos | Capitalização consistente (HTTP, ID, URL) | Http, Id | Alinhamento com golint/revive |
| Variáveis de erro | Sentinelas exportadas com prefixo Err | Estilos mistos ErrorNotFound | Ergonomia para errors.Is |
| Regra | Fazer | Evitar | Justificativa |
|---|---|---|---|
| Contexto | func F(ctx context.Context, ...) primeiro | context em parâmetros intermediários | Propagação de cancelamento |
| Opções | Opções funcionais ou struct de configuração | Longas listas de parâmetros posicionais | APIs compatíveis com o futuro |
| Retornos | Structs/ponteiros concretos | Retornos de interface não exportada | Clareza de tipo para o chamador |
| Parâmetros | Interfaces pequenas no local da chamada | Exportar Interface ampla no pacote produtor | Segregação de interface |
| Nil | Documentar comportamento nil | Panic em nil sem documentação | Bibliotecas previsíveis |
| Tempo | time.Time / time.Duration em APIs | int64 bruto sem unidades | Ambiguidade em APIs públicas |
| Regra | Fazer | Evitar | Justificativa |
|---|---|---|---|
| Erros | Retornar error por último | Panic para falhas esperadas | Controle do chamador |
| Envolvimento (Wrapping) | fmt.Errorf("op: %w", err) | Cadeias opacas de errors.New | Inspeção com Is/As |
| Sentinelas | var ErrX = errors.New(...) estável | Comparação de string em Error() | Clientes frágeis |
| Logging | Deixar a aplicação registrar | log.Printf da biblioteca em erros | Acoplamento de importação |
| Métricas | Hooks/interfaces opcionais | Prometheus codificado | Peso da dependência |
| Regra | Fazer | Evitar | Justificativa |
|---|---|---|---|
| Tag Semver | v1.2.3 em tags de módulo | Tags git ad-hoc | Resolução de go get |
| Alteração que quebra compatibilidade | Bump maior / novo caminho de módulo | Renomear exports em patch | Quebra para o consumidor |
| Depreciado | // Deprecated: use X + issue | Remoção silenciosa | Tempo de migração |
| Experimental | v0 ou internal/ até estabilizar | v1 com mudanças constantes | Definição de expectativas |
| go.mod | Diretiva go corresponde ao CI | Desvio entre módulos | Consistência da toolchain |
| Regra | Fazer | Evitar | Justificativa |
|---|---|---|---|
| Godoc | Frases completas em exports | Comentários vazios ou com nome errado | Qualidade do pkg.go.dev |
| Exemplos | Example* em example_test.go | Amostras apenas no README | Documentação verificada por compilação |
| Testes | package foo_test para visão do consumidor | Apenas testes white-box | Sinal de ergonomia da API |
| Tags de build | Documentar tags de build de integração | //go:build surpresa na API principal | go test do consumidor |
// Preferido: retorno concreto, opções funcionais opcionais
type Client struct { /* ... */ }
type Option func(*Client)
func WithTimeout(d time.Duration) Option { /* ... */ }
func New(opts ...Option) (*Client, error) {
c := &Client{timeout: 30 * time.Second}
for _, o := range opts {
o(c)
}
return c, nil
}// Aceitar interfaces em limites de integração
func RegisterHandler(mux ServeMux, h Handler) { /* ... */ }| Mudança | Impacto Semver | Exemplo |
|---|---|---|
| Campo não exportado adicionado | Patch | Seguro |
| Nova func exportada | Minor | func ParseConfig |
| Mudança de assinatura de func exportada | Major | Mudança de tipo de parâmetro |
| Remoção de símbolo exportado | Major | Excluir LegacyDial |
| Correção de comportamento que quebra chamadores | Major ou flag de recurso | Validação mais rigorosa |
Raramente.
Retorne tipos concretos, a menos que você oculte intencionalmente a implementação atrás de um tipo de interface pequeno que você define.
Não.
Aceite ctx dos chamadores; apenas main de nível superior ou testes criam raízes.
Frequentemente um método.
Consumidores as definem; produtores retornam structs.
Use valores sentinela var ErrFoo.
Inspeção estável supera correspondência de substring em mensagens.
Opções escalam para bibliotecas com muitos padrões.
Structs de configuração funcionam quando os campos são majoritariamente obrigatórios.
Use internal/ até estabilizar, ou permaneça em tags de módulo v0 com avisos claros no README.
Coloque-os em package foo_test ou internal/testutil.
Evite alargar a superfície semver para helpers apenas de teste.
Exporte parâmetros de tipo claros com restrições.
Evite exportar helpers excessivamente genéricos que obscurecem os tipos.
Quase nunca em nomes exportados.
O nome do pacote já fornece contexto (user.New em vez de user.NewUser).
Adicione Deprecated no godoc, mantenha o símbolo, envie a substituição, remova na próxima versão major.
Bibliotecas devem usar ctx para cancelamento/prazos.
Evite exigir chaves de contexto privadas, a menos que documentadas como pontos de extensão opcionais.
staticcheck SA1019 (depreciado), verificações de comentários exportados (revive) e tags de struct do vet.
Combine com revisão humana para a forma.
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).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026