Padrões de Codificação e Diretrizes de API

Os padrões Rust de toda a frota estendem os padrões com layout de projeto, tratamento de erros, política de unsafe e as diretrizes oficiais de API do Rust para crates públicos - aplicados por rustfmt, clippy -D warnings e checklists de revisão.

Receita

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

# Lints do workspace do Cargo.toml (estilo edição 2024)
[workspace.lints.rust]
unsafe_code = "forbid"  # em crates de domínio; permitir em ffi-shim com ADR
 
[workspace.lints.clippy]
unwrap_used = "deny"
expect_used = "warn"
await_holding_lock = "deny"

crates/
  foo-domain/    # sem axum, sqlx, tokio na API pública
  foo-infra/     # adaptadores de IO
  foo-api/       # binário

Quando usar isto:

Inicialização de novo repositório a partir do template
Debates repetidos de PR sobre estilo
Abertura de crate interno para código aberto
Solicitação de consistência de auditoria de segurança

Exemplo de Trabalho

//! Crate de domínio - segue as diretrizes de API: erros tipados, sem panics na API pública.
 
use thiserror::Error;
 
#[derive(Debug, Error)]
pub enum ValidateError {
    #[error("montante negativo: {0}")]
    NegativeAmount(i64),
}
 
/// Retorna o total em centavos - o chamador é responsável pela semântica de validação.
pub fn total_cents(subtotal: i64, tax: i64) -> Result<i64, ValidateError> {
    if subtotal < 0 || tax < 0 {
        return Err(ValidateError::NegativeAmount(subtotal));
    }
    Ok(subtotal + tax)
}

Funções públicas retornam Result; binários mapeiam erros para HTTP na borda.

Mergulho Profundo

Diretrizes de API do Rust (selecionado)

Nomenclatura - funções snake_case, tipos UpperCamelCase, evitar abreviações.
Propriedade - Preferir argumentos emprestados quando o chamador tem os dados; retornar propriedade quando estiver criando.
Erros - Enums thiserror com variantes significativas; sem erros String em bibliotecas.
Documentação - /// em itens públicos com exemplos que compilam em cargo test --doc.
Recursos - Dependências opcionais atrás de flags de recursos; recursos padrão mínimos.

Padrões de Layout

Workspace para serviços multi-crate.
tests/ integração; benches/ para Criterion.
#[cfg(test)] testes unitários ao lado do código.

Checklist de Revisão

A alteração da API pública é apropriada para semver?
unsafe tem comentário de segurança + segundo revisor?
Nova dependência verificada (cargo deny)?
Rastreamento em caminhos visíveis ao usuário?

Armadilhas

clippy allow wall - Derrota a CI. Correção: ADR para permissões em nível de crate com expiração.
Importações de domínio axum - Lógica não testável. Correção: Lint de importação proibida ou teste de unidade de arquitetura.
Alteração de quebra em patch - Correção: Automação de Semver + changelog.
Exemplos de documentação não compilam - Correção: cargo test --doc em CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`#![forbid(unsafe_code)]` em todos os lugares	Domínio puro	Crate de shim FFI
Regras de fmt apenas para nightly	Equipe concorda	MSRV estável CI
Lints de derive personalizados	API específica da organização	Clippy upstream cobre isso

FAQs

Largura da linha?

100 padrão comum; corresponder a rustfmt.toml de toda a frota.

pub use re-exports?

Minimizar na API pública; preferir caminhos explícitos por diretrizes de API.

async na API pública da biblioteca?

Preferir síncrono ou abstrair com traits; async fn em traits quando estável para sua política MSRV.

Padrões de aplicação vs. biblioteca?

Mais rigoroso em crates publicados; binários podem usar anyhow na raiz.

Violações antigas?

Rastrear em tickets de débito; sem novas violações em arquivos tocados (ratchet).

Relacionado

Diretrizes de API do Rust - regras detalhadas
Melhores Práticas de Linting - ferramentas
Cultura de Revisão de Código - aplicação
Governança de Dependências e Unsafe - segurança
Convenções de Documentação - documentação

Versões da Stack: 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+.

Padrões de Codificação e Diretrizes de API

Receita

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

# Lints do workspace do Cargo.toml (estilo edição 2024)
[workspace.lints.rust]
unsafe_code = "forbid"  # em crates de domínio; permitir em ffi-shim com ADR
 
[workspace.lints.clippy]
unwrap_used = "deny"
expect_used = "warn"
await_holding_lock = "deny"

crates/
  foo-domain/    # sem axum, sqlx, tokio na API pública
  foo-infra/     # adaptadores de IO
  foo-api/       # binário

Quando usar isto:

Inicialização de novo repositório a partir do template
Debates repetidos de PR sobre estilo
Abertura de crate interno para código aberto
Solicitação de consistência de auditoria de segurança

Exemplo de Trabalho

//! Crate de domínio - segue as diretrizes de API: erros tipados, sem panics na API pública.
 
use thiserror::Error;
 
#[derive(Debug, Error)]
pub enum ValidateError {
    #[error("montante negativo: {0}")]
    NegativeAmount(i64),
}
 
/// Retorna o total em centavos - o chamador é responsável pela semântica de validação.
pub fn total_cents(subtotal: i64, tax: i64) -> Result<i64, ValidateError> {
    if subtotal < 0 || tax < 0 {
        return Err(ValidateError::NegativeAmount(subtotal));
    }
    Ok(subtotal + tax)
}

Funções públicas retornam Result; binários mapeiam erros para HTTP na borda.

Mergulho Profundo

Diretrizes de API do Rust (selecionado)

Nomenclatura - funções snake_case, tipos UpperCamelCase, evitar abreviações.
Propriedade - Preferir argumentos emprestados quando o chamador tem os dados; retornar propriedade quando estiver criando.
Erros - Enums thiserror com variantes significativas; sem erros String em bibliotecas.
Documentação - /// em itens públicos com exemplos que compilam em cargo test --doc.
Recursos - Dependências opcionais atrás de flags de recursos; recursos padrão mínimos.

Padrões de Layout

Workspace para serviços multi-crate.
tests/ integração; benches/ para Criterion.
#[cfg(test)] testes unitários ao lado do código.

Checklist de Revisão

A alteração da API pública é apropriada para semver?
unsafe tem comentário de segurança + segundo revisor?
Nova dependência verificada (cargo deny)?
Rastreamento em caminhos visíveis ao usuário?

Armadilhas

clippy allow wall - Derrota a CI. Correção: ADR para permissões em nível de crate com expiração.
Importações de domínio axum - Lógica não testável. Correção: Lint de importação proibida ou teste de unidade de arquitetura.
Alteração de quebra em patch - Correção: Automação de Semver + changelog.
Exemplos de documentação não compilam - Correção: cargo test --doc em CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`#![forbid(unsafe_code)]` em todos os lugares	Domínio puro	Crate de shim FFI
Regras de fmt apenas para nightly	Equipe concorda	MSRV estável CI
Lints de derive personalizados	API específica da organização	Clippy upstream cobre isso

FAQs

Largura da linha?

100 padrão comum; corresponder a rustfmt.toml de toda a frota.

pub use re-exports?

Minimizar na API pública; preferir caminhos explícitos por diretrizes de API.

async na API pública da biblioteca?

Preferir síncrono ou abstrair com traits; async fn em traits quando estável para sua política MSRV.

Padrões de aplicação vs. biblioteca?

Mais rigoroso em crates publicados; binários podem usar anyhow na raiz.

Violações antigas?

Rastrear em tickets de débito; sem novas violações em arquivos tocados (ratchet).

Relacionado

Diretrizes de API do Rust - regras detalhadas
Melhores Práticas de Linting - ferramentas
Cultura de Revisão de Código - aplicação
Governança de Dependências e Unsafe - segurança
Convenções de Documentação - documentação

Versões da Stack: 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+.

Padrões de Codificação e Diretrizes de API

Buscar na documentação

Padrões de Codificação e Diretrizes de API