Boas Práticas de Arquitetura
Limites, coesão e estabilidade da API mantêm bases de código Rust sustentáveis à medida que equipes e tráfego crescem.
Como Usar Esta Lista
- Aplique no início de projetos novos (greenfield) e em revisões trimestrais de arquitetura.
- Use em conjunto com o Checklist de Decisões de Arquitetura.
A - Limites (Boundaries)
- Lógica de domínio em crate(s) dedicados. Sem
axum/sqlxno domínio. - Direção de dependência para dentro.
infra->domain<-api. - Binários leves.
mainapenas configura e inicia o servidor. - DTOs nas bordas. Tipos Serde != tipos de domínio quando as regras diferem.
- Portas como traits. Adaptadores substituíveis para teste/produção.
B - API e Erros
- API pública do crate estável e documentada. Semver respeitado para bibliotecas.
- Erros tipados por contexto. Mapeados para HTTP/gRPC na borda.
- Validação na construção. Estados de domínio ilegais não representáveis.
- Mudanças que quebram a versão via ADR + migração. Changelog para consumidores.
- Feature flags documentadas em tempo de compilação vs. tempo de execução.
C - Workspace e Build
-
[workspace.dependencies]fixados.serde,tokio,axumalinhados. - CI testa
--workspace. Todos os membros verdes. - Política de MSRV aplicada.
rust-versionnos manifestos. - Extrair crates quando o grafo de compilação prejudica. Não nano-crates preemptivos.
- Lint de dependência proibida para o domínio (script opcional).
D - Operações
- Configuração validada no boot. Falhar rapidamente em env inválido.
- Observabilidade básica.
tracing+metrics+health. - Desligamento gracioso. Drena trabalho em andamento.
- Migrações separadas do serviço. Job ou fase na implantação.
- Segredos nunca no repositório/imagens.
E - Processo
- ADRs para forks de arquitetura. Vincular decisões do checklist.
- Auditar checklist trimestralmente. Rastrear itens de débito técnico.
- Refatorar incrementalmente. Testes protegem extrações.
- Referência de problema/solução atualizada quando padrões se repetem.
- Onboarding lê ARCHITECTURE.md no primeiro dia.
FAQs
crates mínimos?
domain + api + infra para um serviço Axum/sqlx típico.
monolito ok?
Até 2+ implantáveis ou dor de compilação; depois, workspace.
kernel compartilhado?
Crate de tipos ok; evitar "depósito de lixo".
microsserviços?
Cada serviço tem seu próprio workspace; compartilhar a biblioteca de domínio via publicação de crate.
BFF para frontend?
Opcional: crate api adaptado para DTOs de UI, separado do crate da API pública.
pipeline de dados?
Crate de worker polars; API orquestra jobs assincronamente.
revisões de segurança?
Limite do crate auth + auditoria de cadeia de suprimentos.
diagramas de documentação?
C4 ou dependência simples em mermaid em ARCHITECTURE.md.
impor limites?
Script de CI busca importações proibidas no domínio.
exceção de legado?
ADR com marco de remoção; sem exceção ilimitada.
Relacionados
- Checklist de Decisões de Arquitetura
- Limites de Workspace e Crate
- Decisões de Arquitetura Rust
- 50 Regras Rust
Versões das Ferramentas: 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+.