AGENT SKILL
rust-workspace-patterns
Use when structuring Rust workspaces. Layouts and splits.
- License 许可
- MIT
- 所属仓库
- iberi22/skills
- 最近更新
- 2026-10-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rust-workspace-patterns
- author
- Hermes Agent for belal
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "rust", "workspace", "patterns", "organization", "architecture", "dependency", "feature-flags" ], "references": [ { "url": "https://doc.rust-lang.org/cargo/reference/workspaces.html", "year": 2026, "title": "Cargo Workspaces — Official Documentation" }, { "url": "https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html", "year": 2021, "title": "Keep Your Architecture Documentation Clean — matklad" }, { "url": "https://rust-lang.github.io/api-guidelines/", "year": 2026, "title": "Rust API Guidelines — C-CARGO" }, { "url": "https://github.com/rust-derive-eq/example-project", "year": 2024, "title": "Example Rust Workspace Project Structure" } ], "related_skills": [ "rust-compile-optimization", "cargo-wizard", "rust-code-quality-audit" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Use when structuring Rust workspaces. Layouts and splits.
03 SKILL.md 正文
Rust Workspace Patterns — Organización de Código y Dependencias
Cuándo usar
- Organizar un proyecto Rust con múltiples crates
- Decidir cómo dividir un monolito en workspaces
- Gestionar dependencias compartidas entre crates
- Configurar feature flags para compilación condicional
- Crear un workspace desde cero con estructura correcta
- Auditar la organización de un workspace existente
Estructura canónica de un workspace
my-project/
├── Cargo.toml # Workspace root
├── crates/
│ ├── core/ # Domain logic (sin dependencias externas pesadas)
│ │ ├── Cargo.toml
│ │ └── src/
│ ├── api/ # HTTP/REST layer (depends on core)
│ │ ├── Cargo.toml
│ │ └── src/
│ ├── cli/ # CLI binary (depends on core + api)
│ │ ├── Cargo.toml
│ │ └── src/
│ └── proto/ # Shared types (seria/JSON schema)
│ ├── Cargo.toml
│ └── src/
├── scripts/ # Build/test scripts
├── .cargo/
│ └── config.toml # Workspace-wide cargo config
└── README.md
Regla de dependencias: Capas
# core/Cargo.toml — SIN dependencias de la organización
[dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["rt", "macros"] }
# api/Cargo.toml — DEPENDE de core
[dependencies]
my-project-core = { path = "../core" }
axum = "0.7"
tower = "0.4"
# cli/Cargo.toml — DEPENDE de core + api
[dependencies]
my-project-core = { path = "../core" }
my-project-api = { path = "../api" }
clap = { version = "4", features = ["derive"] }
Regla: Nunca crear dependencias circulares. core no depende de api ni cli.
Feature flags para compilación condicional
En un crate
# core/Cargo.toml
[features]
default = ["json"]
json = ["serde_json"]
sqlite = ["rusqlite"]
enterprise = [] # Feature vacía para código condicional
[dependencies]
serde_json = { version = "1", optional = true }
rusqlite = { version = "0.31", optional = true }
// core/src/lib.rs
#[cfg(feature = "json")]
pub mod json_support;
#[cfg(feature = "sqlite")]
pub mod sqlite_store;
#[cfg(feature = "enterprise")]
pub mod enterprise_features;
En el workspace
# Cargo.toml (workspace root)
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["rt", "macros"] }
# crates heredan la versión exacta del workspace
# core/Cargo.toml
[dependencies]
serde.workspace = true
tokio.workspace = true
Activar features desde CLI
# Solo con feature "enterprise"
cargo build --features enterprise
# Con múltiples features
cargo build --features "json,sqlite"
# Sin features por defecto
cargo build --no-default-features
# En workspace
cargo build --workspace --features my-crate/enterprise
Patrones de organización
1. Proto/Shared types crate
Para tipos compartidos entre frontend (TS/Flutter) y backend (Rust):
proto/
├── Cargo.toml
├── src/
│ ├── lib.rs
│ ├── agent.rs # AgentMessage, AgentState
│ ├── memory.rs # MemoryEntry, QueryResult
│ └── event.rs # EventType, EventPayload
├── schemas/ # JSON Schema (generado)
└── scripts/
└── build.sh # Genera schemas + types TS
# proto/Cargo.toml
[dependencies]
serde = { version = "1", features = ["derive"] }
schemars = "0.8" # Para JSON Schema
2. Adapter pattern (Hexagonal architecture)
// core/src/ports/mod.rs — Interfaces (trait objects)
pub mod storage {
pub trait Storage: Send + Sync {
fn save(&self, key: &str, value: &[u8]) -> Result<()>;
fn load(&self, key: &str) -> Result<Option<Vec<u8>>>;
}
}
// adapters/src/sqlite.rs — Implementación concreta
pub struct SqliteStorage {
conn: rusqlite::Connection,
}
impl core::ports::storage::Storage for SqliteStorage {
fn save(&self, key: &str, value: &[u8]) -> Result<()> {
// Implementación SQLite
}
// ...
}
3. Error handling por capa
// core/src/error.rs — Errores del dominio
#[derive(Debug, thiserror::Error)]
pub enum CoreError {
#[error("Not found: {0}")]
NotFound(String),
#[error("Validation failed: {0}")]
Validation(String),
#[error("Internal error: {0}")]
Internal(#[from] anyhow::Error),
}
// api/src/error.rs — Errores HTTP (usa core errors)
#[derive(Debug, thiserror::Error)]
pub enum ApiError {
#[error(transparent)]
Core(#[from] core::CoreError),
#[error("Unauthorized")]
Unauthorized,
}
impl IntoResponse for ApiError {
fn into_response(self) -> Response {
match self {
ApiError::Core(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()).into_response(),
ApiError::Unauthorized => (StatusCode::UNAUTHORIZED, "Unauthorized").into_response(),
}
}
}
4. Config centralizado
// config/src/lib.rs — Config compartida
use serde::Deserialize;
#[derive(Debug, Deserialize, Clone)]
pub struct AppConfig {
pub database: DatabaseConfig,
pub server: ServerConfig,
pub features: FeatureFlags,
}
#[derive(Debug, Deserialize, Clone)]
pub struct FeatureFlags {
pub enterprise: bool,
pub analytics: bool,
}
// Uso en api
pub async fn start_server(config: AppConfig) {
let app = Router::new()
.route("/", get(health))
.with_state(config.server);
}
5. Test helpers compartidos
crates/
├── core/
│ ├── src/
│ └── tests/
│ └── common/
│ └── mod.rs # Test fixtures
├── api/
│ ├── src/
│ └── tests/
│ └── common/
│ └── mod.rs # Re-exporta core::tests::common
Gestión de dependencias
Verificar dependencias no usadas
# Detectar dependencias no usadas
cargo machete
# Verificar features activas
cargo tree -e features
# Verificar dependencias duplicadas
cargo tree --duplicates
Actualizar dependencias
# Verificar updates disponibles
cargo outdated
# Actualizar todas
cargo update
# Actualizar una específica
cargo update -p serde
Dependencias del workspace
# Cargo.toml (workspace root)
[workspace.dependencies]
# Definir versiones una vez
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["rt", "macros"] }
# En crates individuales
# core/Cargo.toml
[dependencies]
serde.workspace = true
tokio.workspace = true
Patrones anti-patrones
❌ Monolito gigante
// src/main.rs — 5000 líneas, TODO mezclado
fn main() {
// HTTP handlers, DB logic, CLI parsing, business logic...
}
✅ Workspace separado
crates/
├── core/ # Business logic
├── api/ # HTTP layer
├── cli/ # CLI interface
└── proto/ # Shared types
❌ Dependencias circulares
# core/Cargo.toml
[dependencies]
my-project-api = { path = "../api" } # ❌ core no debería depender de api
✅ Dependency inversion
// core define el trait
pub trait ApiClient: Send + Sync {
fn send_request(&self, url: &str) -> Result<Response>;
}
// api implementa el trait
impl ApiClient for ReqwestClient {
fn send_request(&self, url: &str) -> Result<Response> {
// reqwest implementation
}
}
Comandos útiles para workspaces
# Build todo el workspace
cargo build --workspace
# Test todo el workspace
cargo test --workspace
# Test un crate específico
cargo test -p my-crate
# Clippy en todo
cargo clippy --workspace
# Formatear todo
cargo fmt --all
# Verificar compilación sin build
cargo check --workspace
# Ver miembros del workspace
cargo metadata --format-version 1 | jq '.workspace_members'
Referencias
- Cargo Workspaces (Official): https://doc.rust-lang.org/cargo/reference/workspaces.html — Documentación oficial de Cargo.
- ARCHITECTURE.md (matklad): https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html — Cómo documentar arquitectura de proyectos Rust.
- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/ — Guidelines para APIs de Rust.
- Cargo Book (Workspaces): https://doc.rust-lang.org/cargo/book/workspaces.html — Guía de workspaces.
- Rust Design Patterns: https://rust-unofficial.github.io/patterns/ — Patrones de diseño en Rust.
- Thiserror: https://github.com/dtolnay/thiserror — Derive macro para errores.
- Anyhow: https://github.com/dtolnay/anyhow — Error handling para applications.
- Schemars: https://github.com/GREsau/schemars — JSON Schema generation desde Rust.
Pitfalls
| Problema | Causa | Solución |
|---|---|---|
| "cycle detected" en cargo | Dependencias circulares | Revisar el grafo de dependencias con cargo tree |
| Feature unification problem | Features se unen en workspace | Usar resolver = "2" en workspace root |
| Test helpers duplicados | Cada crate tiene sus propios fixtures | Crear crate test-utils compartido |
| Path dependency hell | Muchos crates con path = "../" |
Considerar crates.io o git deps para crates estables |
| Stale feature flags | Features que nadie usa | cargo machete + revisar cfg(feature = "...") en código |
| Build times explode | Workspace muy grande | Split en sub-workspaces o reducir dependencies |
Rust Workspace Patterns — v1.0.0
04 同仓库更多 Skills
web-design-guidelines
暂无简介
★ 0
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall. Recovers the page via archives and provenance-checked fallbacks.
★ 0
studio-coach
暂无简介
★ 0
src-generator
暂无简介
★ 0
sqlite-pro
暂无简介
★ 0
rigor-evaluator
Use when you need a quick heuristic rigor score (10 criteria, 0-2 each) for the features in a .gitcore/features.json file, to decide which features are ready to ship.
★ 0