Diretrizes de API Rust

Siga a mentalidade das diretrizes oficiais de API Rust: nomenclatura previsível, conversões claras, construtores falíveis e tipos ergonômicos, mas difíceis de usar incorretamente.

Receita

/// Analisa um slug a partir da entrada do usuário.
pub fn from_str(s: &str) -> Result<Slug, ParseError> { /* ... */ }
 
impl TryFrom<String> for Slug { /* ... */ }
 
impl AsRef<str> for Slug { fn as_ref(&self) -> &str { &self.0 } }

Quando usar isso: Ao projetar qualquer API de crate pub consumida por outras equipes ou pelo crates.io.

Exemplo de Trabalho

Convenções de nomenclatura:

Prefixo	Custo	Exemplo
`as_`	grátis	`as_str()`
`to_`	pode alocar	`to_string()`
`into_`	consome `self`	`into_inner()`

pub struct Config { /* ... */ }
 
impl Config {
    pub fn builder() -> ConfigBuilder { ConfigBuilder::default() }
    pub fn validate(&self) -> Result<(), ValidationError> { /* ... */ }
}

O que isso demonstra:

Análise falível via estilo TryFrom/from_str
Empréstimos baratos via AsRef
Builder para muitos campos opcionais
Métodos de validação em tipos construídos

Mergulho Profundo

C-GETTER: getters nomeados como o campo sem o prefixo get_, a menos que haja confusão
C-CTOR: construtores new, with_*, from_*
C-ERROR: tipos de erro com sufixo Error, cadeia source()
C-DEBUG: Debug para logs, Display para usuários
Interoperação: serde por trás de um sinalizador de recurso para bibliotecas

Armadilhas

Prefixo get_ em tudo - não idiomático. Correção: fn len(&self) em vez de get_len.
into_ que copia - nome enganoso. Correção: renomear para to_ ou mover o consumo real.
Construtores que entram em pânico - new deve ser infalível ou retornar Result. Correção: try_new.
Vazamento de tipos internos - prisão semântica de versão futura. Correção: newtype ou campos privados.
Funcionalidade excessiva em recursos padrão - dependências pesadas. Correção: recursos opcionais documentados.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
API apenas com Builder	muitos campos opcionais	struct de dois campos
`Deref` para o interno	wrapper transparente	ocultar invariantes

FAQs

URL completa das diretrizes?

Livro de diretrizes de API Rust (oficial) - alinhe a lista de verificação da equipe com ele.

`pub use` reexportações?

#[doc(inline)] para caminhos estáveis; evite caminhos internos profundos na documentação pública.

traits selados?

Evita implementações downstream em traits de extensão que não se destinam à implementação fora do crate.

semver para API?

Alterações que quebram a compatibilidade: remover/renomear itens pub, apertar genéricos, alterar semântica de Erro.

async fn em trait?

Traits assíncronos da Edição 2024 ou o crate async_trait com limites Send documentados.

Nomenclatura do Iterator?

O trio padrão iter, iter_mut, into_iter.

Display vs Debug de erro?

Display para o usuário; Debug para engenheiros; thiserror lida com ambos.

must_use?

Em builders que retornam Result e futures que os usuários não devem ignorar.

atributo deprecated?

#[deprecated(note = "use x")] com caminho de migração antes da remoção.

módulo prelude?

pub mod prelude { pub use ... } para importações ergonômicas.

Relacionado

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.

Diretrizes de API Rust

Siga a mentalidade das diretrizes oficiais de API Rust: nomenclatura previsível, conversões claras, construtores falíveis e tipos ergonômicos, mas difíceis de usar incorretamente.

Receita

/// Analisa um slug a partir da entrada do usuário.
pub fn from_str(s: &str) -> Result<Slug, ParseError> { /* ... */ }
 
impl TryFrom<String> for Slug { /* ... */ }
 
impl AsRef<str> for Slug { fn as_ref(&self) -> &str { &self.0 } }

Quando usar isso: Ao projetar qualquer API de crate pub consumida por outras equipes ou pelo crates.io.

Exemplo de Trabalho

Convenções de nomenclatura:

Prefixo	Custo	Exemplo
`as_`	grátis	`as_str()`
`to_`	pode alocar	`to_string()`
`into_`	consome `self`	`into_inner()`

pub struct Config { /* ... */ }
 
impl Config {
    pub fn builder() -> ConfigBuilder { ConfigBuilder::default() }
    pub fn validate(&self) -> Result<(), ValidationError> { /* ... */ }
}

O que isso demonstra:

Análise falível via estilo TryFrom/from_str
Empréstimos baratos via AsRef
Builder para muitos campos opcionais
Métodos de validação em tipos construídos

Mergulho Profundo

C-GETTER: getters nomeados como o campo sem o prefixo get_, a menos que haja confusão
C-CTOR: construtores new, with_*, from_*
C-ERROR: tipos de erro com sufixo Error, cadeia source()
C-DEBUG: Debug para logs, Display para usuários
Interoperação: serde por trás de um sinalizador de recurso para bibliotecas

Armadilhas

Prefixo get_ em tudo - não idiomático. Correção: fn len(&self) em vez de get_len.
into_ que copia - nome enganoso. Correção: renomear para to_ ou mover o consumo real.
Construtores que entram em pânico - new deve ser infalível ou retornar Result. Correção: try_new.
Vazamento de tipos internos - prisão semântica de versão futura. Correção: newtype ou campos privados.
Funcionalidade excessiva em recursos padrão - dependências pesadas. Correção: recursos opcionais documentados.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
API apenas com Builder	muitos campos opcionais	struct de dois campos
`Deref` para o interno	wrapper transparente	ocultar invariantes

FAQs

URL completa das diretrizes?

Livro de diretrizes de API Rust (oficial) - alinhe a lista de verificação da equipe com ele.

`pub use` reexportações?

#[doc(inline)] para caminhos estáveis; evite caminhos internos profundos na documentação pública.

traits selados?

Evita implementações downstream em traits de extensão que não se destinam à implementação fora do crate.

semver para API?

Alterações que quebram a compatibilidade: remover/renomear itens pub, apertar genéricos, alterar semântica de Erro.

async fn em trait?

Traits assíncronos da Edição 2024 ou o crate async_trait com limites Send documentados.

Nomenclatura do Iterator?

O trio padrão iter, iter_mut, into_iter.

Display vs Debug de erro?

Display para o usuário; Debug para engenheiros; thiserror lida com ambos.

must_use?

Em builders que retornam Result e futures que os usuários não devem ignorar.

atributo deprecated?

#[deprecated(note = "use x")] com caminho de migração antes da remoção.

módulo prelude?

pub mod prelude { pub use ... } para importações ergonômicas.

Relacionado

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.

Diretrizes de API Rust

Buscar na documentação

Diretrizes de API Rust