Boas Práticas de Arquitetura

Q: crates mínimos?

domain + api + infra para um serviço Axum/sqlx típico.

Q: monolito ok?

Até 2+ implantáveis ou dor de compilação; depois, workspace.

Q: kernel compartilhado?

Crate de tipos ok; evitar "depósito de lixo".

Q: microsserviços?

Cada serviço tem seu próprio workspace; compartilhar a biblioteca de domínio via publicação de crate.

Q: BFF para frontend?

Opcional: crate api adaptado para DTOs de UI, separado do crate da API pública.

Q: pipeline de dados?

Crate de worker polars; API orquestra jobs assincronamente.

Q: revisões de segurança?

Limite do crate auth + auditoria de cadeia de suprimentos.

Q: diagramas de documentação?

C4 ou dependência simples em mermaid em ARCHITECTURE.md.

Q: impor limites?

Script de CI busca importações proibidas no domínio.

Q: exceção de legado?

ADR com marco de remoção; sem exceção ilimitada.

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/sqlx no domínio.
Direção de dependência para dentro. infra -> domain <- api.
Binários leves. main apenas 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, axum alinhados.
CI testa --workspace. Todos os membros verdes.
Política de MSRV aplicada. rust-version nos 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

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

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/sqlx no domínio.
Direção de dependência para dentro. infra -> domain <- api.
Binários leves. main apenas 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, axum alinhados.
CI testa --workspace. Todos os membros verdes.
Política de MSRV aplicada. rust-version nos 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

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

Boas Práticas de Arquitetura

Buscar na documentação

Boas Práticas de Arquitetura