Checklist de Decisão de Arquitetura
Percorra esta checklist ao iniciar ou reestruturar uma base de código Rust para que os limites dos crates, erros e ferramentas sejam deliberados antes que a inércia se instale.
Como Usar Esta Checklist
- Complete o nível de fundação antes de escrever código de funcionalidade.
- Registre cada escolha no README ou ADR com o proprietário.
- Revise após o primeiro tráfego de produção.
Fundação
- Toolchain: Fixar Rust 1.97.0, edition 2024,
rust-toolchain.tomlcommitado. - Layout: Workspace com crates
domain,api,infravs. crate único (justificar em ADR). - Política de gerenciador de pacotes:
Cargo.lockcommitado para aplicações. - MSRV:
rust-version = "1.97"nos manifestos; matriz de CI corresponde. - Política de Lint:
fmt --check,clippy -D warnings, documentado em CONTRIBUTING.
Limites
- Pureza do domínio: Sem importações de axum/sqlx no crate de domínio.
- Camada HTTP: Handlers do Axum 0.8 finos; chamam serviços de domínio.
- Persistência: Traits de repositório no domínio; impl do sqlx 0.8 em infra.
- Erros: Erros de domínio
thiserror; mapear para HTTP no crate de api. - Configuração: Configurações tipadas a partir de env; segredos do armazenamento da plataforma.
Qualidade e Operações
- Testes: Unidade de domínio, integração HTTP, migrações sqlx em CI.
- Observabilidade: Logs JSON
tracing, rotas de health/readiness. - Desligamento gracioso: Tratamento SIGTERM com timeout de drain.
- Migrações:
sqlx migrateou job estilo flyway; não apenas na inicialização. - Artefato de deploy: Binário de release em container mínimo ou estático onde couber.
FAQs
Pular workspace para MVP?
Aceitável a curto prazo; planejar extração ADR antes que a segunda equipe se junte.
Quando usar Polars?
Crate de worker separado se o caminho for de analytics; não dentro do caminho quente de requisição por padrão.
Flags de funcionalidade?
Features do Cargo para tempo de compilação; flags em tempo de execução via serviço de configuração.
Estrutura de docs?
ARCHITECTURE.md linka para a data de conclusão desta checklist.
Código aberto?
LICENSE, SECURITY.md, CODE_OF_CONDUCT no nível de fundação.
Múltiplos binários?
Membros do workspace por binário compartilhando o crate de domínio.
API proto?
Adicionar membro do crate tonic; REST e gRPC compartilham o domínio.
Camada de autenticação?
Adicionar decisão de middleware JWT antes do lançamento público.
Limites de taxa?
Decisão de limitador tower Governor/Redis na borda.
Assinatura de conclusão?
Tick de engenheiro de staff + data em ARCHITECTURE.md.
Relacionados
- Workspace & Limites de Crate
- Decisões de Arquitetura Rust
- Estratégia de Erros
- Melhores Práticas de Arquitetura
Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.