Melhores Práticas para Backends Web

Regras de recomendação para serviços HTTP Rust de fácil manutenção, seguros e rápidos.

Como Usar Esta Lista

• Revise durante revisões de design e antes de implantações em produção.
• Converta falhas repetidas em lints Clippy, verificações de CI ou ADRs.
• Releia após grandes atualizações do Axum ou Tokio.

A - Estrutura do Projeto

• Mantenha os handlers enxutos; coloque a lógica de negócios em serviços. Teste serviços sem HTTP.
• Um módulo de roteador por área de domínio. users.rs, billing.rs, não um único arquivo gigante.
• Coloque os DTOs junto com as rotas ou em um módulo schemas. Separe tipos de entrada e saída.
• Compartilhe tipos de domínio através de um crate core em workspaces. Evite copiar structs entre binários.
• Documente os contratos da API pública. OpenAPI ou README com tabelas de códigos de status.

B - Erros e Validação

• Um enum AppError implementando IntoResponse. Formato de erro JSON estável em todos os lugares.
• Valide na fronteira HTTP. Serde + validator antes das chamadas ao banco de dados.
• Retorne 422 para falhas de validação semântica. Documente códigos de erro por campo.
• Registre 5xx com ID da requisição; oculte detalhes internos dos clientes. Sem traces de pilha em JSON.
• Nunca use unwrap em handlers. Use ? e erros tipados.

C - Estado e Acesso a Dados

• Armazene sqlx::PgPool em AppState por trás de Clone. O pool é internamente semelhante a Arc.
• Dimensionamento de pools de conexão com base na contagem de workers e limites do DB. Evite pool × workers > max_connections.
• Use transações para escritas em várias etapas. Veja a página de Transações.
• Defina timeouts de statement nas conexões do pool. Evite consultas descontroladas.
• Prefira drivers async de ponta a ponta. Sem I/O bloqueante de postgres em handlers async.

D - Middleware e Segurança

• Aplique camadas de tracing, timeout e limite de corpo globalmente. Ajuste exceções por rota para SSE.
• Autentique subárvores protegidas com camadas de rota. O endpoint de health check permanece não autenticado.
• Nunca registre tokens, cookies ou senhas. Redija cabeçalhos Authorization em traces.
• Habilite CORS deliberadamente. Não use permissive() em produção sem revisão.
• Termine TLS na borda ou use rustls consistentemente. Sem caminhos mistos de bypass de TLS.

E - Performance e Operações

• Faça profiling antes de otimizar a escolha do framework. Meça a latência do DB e de serviços upstream primeiro.
• Defina graceful shutdown em axum::serve. Drene requisições em andamento ao receber SIGTERM.
• Exponha /health e /ready separadamente. Ready verifica a conectividade com o DB.
• Use tracing estruturado com tracing + subscriber JSON em produção. Correlacione com IDs de requisição.
• Teste de carga com payloads realistas. Inclua autenticação e serialização em benchmarks.

FAQs

Relacionados

• Noções Básicas de Backends Web - Primeiros passos
• Tratamento de Erros em Handlers - Enums de erro
• Middleware e Tower - Pilha de camadas
• Testando Serviços Web - Harness de teste
• Melhores Práticas de Banco de Dados - Regras da camada de dados

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+.