Orientação da Base de Código

Aprenda um workspace Rust lendo os limites do Cargo.toml, rastreando o caminho main do binário e mapeando onde residem os erros, a configuração e os tipos de domínio.

Receita

# Visão geral do workspace
cat Cargo.toml
cargo tree --depth 2
rg "^\[workspace\]" -l
 
# Pontos de entrada
fd main.rs
rg "#\[tokio::main\]" -l
 
# Superfície da API pública
cargo doc --no-deps --open

Quando usar isto:

• Primeiro dia em um novo repositório
• Antes de propor um refatoramento de arquitetura
• Após uma divisão significativa do workspace

Exemplo de Trabalho

Layout típico de workspace de serviço Axum:

billing/
  Cargo.toml          # raiz do workspace
  crates/
    api/              # binário: servidor HTTP
      src/main.rs
      src/routes/
      src/state.rs
    domain/           # lib: lógica de negócios, sem axum
    infra/            # lib: adaptadores sqlx, reqwest
  migrations/         # sqlx migrate

Ordem de leitura:

1. Cargo.toml raiz, membros do workspace e dependências compartilhadas
2. api/src/main.rs - inicialização, rastreamento, criação de pool
3. domain/src/lib.rs - tipos e traits principais
4. infra - como os clientes DB e HTTP implementam os traits
5. migrations/ - verdade do esquema

O que isto demonstra:

• Binários são finos; o domínio permanece agnóstico ao framework
• Direção da dependência: api -> domain <- infra
• Migrações residem fora dos caminhos de código quente

Mergulho Profundo

Perguntas para Responder na Primeira Hora

Ferramentas de Navegação

• rg "struct AppState" - estado compartilhado do manipulador
• cargo doc - rustdoc em itens públicos
• rust-analyzer goto-def entre crates

Armadilhas

• Começar no crate errado - falta de contexto do workspace. Correção: sempre Cargo.toml raiz primeiro.
• Ignorar flags de feature - código "faltando" no IDE. Correção: verifique Cargo.toml [features].
• Assumir binário único - o workspace tem muitos. Correção: cargo metadata | jq '.packages[].targets'.
• Docs apenas no README - obsoleto. Correção: confie em cargo doc e ADRs de architecture/.
• Pular migrações - modelo mental incorreto das entidades. Correção: leia o esquema SQL precocemente.

Alternativas

FAQs

Relacionados

• Padrões de estrutura de projeto
• Workspaces
• Checklist de Onboarding de Desenvolvedores
• Pesquisa e regex

Versões de 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+.