Rust

Rust 开发指导

任务目标

指导开发者使用 Rust 构建各领域生产级应用。聚焦领域选择、架构决策、模式选择和陷阱避免，而非语法教程或 API 文档。

核心价值：帮助开发者在每个关键决策点做出正确选择。

使用原则

• 先判断问题落在哪一层：语言机制、设计选择，还是领域约束
• 默认组合 1 个基础技能 + 1 个领域或横切技能，避免一次加载过多技能
• 遇到错误、性能、并发和安全问题时，优先切到对应专门技能，而不是在总技能里硬讲
• 参考文档只承载补充信息，主技能负责路由和决策

触发条件

用户需要以下任一场景时使用：

• 新建 Rust 项目并确定技术方向/架构设计
• 选择框架或 crate（Web/CLI/嵌入式等）
• 处理所有权、生命周期、并发问题
• 设计错误处理策略
• 性能优化或内存调优
• 准备发布到 crates.io 或生产环境

Rust 能做什么：应用领域全景

┌─────────────────────────────────────────────────────────────────────┐
│                        Rust 应用领域全景图                            │
├─────────────┬─────────────┬─────────────┬───────────────────────────┤
│   系统工具   │   Web 服务   │   数据系统   │      桌面/客户端          │
├─────────────┼─────────────┼─────────────┼───────────────────────────┤
│ · ripgrep   │ · axum      │ · Databend  │ · Tauri                  │
│ · fd        │ · actix-web │ · GreptimeDB│ · Slint UI               │
│ · bat       │ · rocket    │ · Qdrant    │ · Alacritty              │
│ · eza       │ · poem      │ · SurrealDB │ · cosmic-text            │
│ · zoxide    │ · warp      │ · Redpanda  │                         │
│ · just      │             │ · sled      │                         │
│ · starship  │             │             │                         │
├─────────────┼─────────────┼─────────────┼───────────────────────────┤
│   区块链     │   嵌入式/IoT  │   游戏开发   │   AI/ML                 │
├─────────────┼─────────────┼─────────────┼───────────────────────────┤
│ · Solana    │ · RTIC      │ · Bevy      │ · candle (HF)            │
│ · Polkadot  │ · embassy   │ · Fyrox     │ · burn                   │
│ · Zcash     │ · no_std    │ · ggez      │ · tch-rs                 │
│ · sui       │ · STM32     │ · macroquad │                         │
│ · Starknet  │ · RISC-V    │ · Embark    │                         │
└─────────────┴─────────────┴─────────────┴───────────────────────────┘

领域选择决策矩阵

项目架构决策

模块 vs Crate：当前共识

"Module First, Crate Last" — 过度拆分 crate 会带来"编译税"

# ✅ 正确：大多数项目用模块即可
my-app/
├── src/
│   ├── main.rs          # 入口
│   ├── lib.rs           # pub use 重导出
│   ├── config.rs        # 配置管理
│   ├── error.rs         # 错误类型定义
│   ├── domain/          # 领域模型
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── infrastructure/  # 基础设施
│   │   ├── mod.rs
│   │   └── database.rs
│   └── handlers/        # 处理层 (Web)
│       └── mod.rs

何时必须拆分 crate：

1. 需要过程宏（Procedural Macro）—— 语言强制要求独立 crate
2. 需要编译器级别的边界隔离 —— 确保 Module A 无法看到 Module B 的私有内部
3. 需要编译并行加速 —— 两个大型独立模块可以同时编译

标准项目模板结构

project-name/
├── Cargo.toml              # workspace 根（如需要）
├── rust-toolchain.toml     # 锁定 Rust 版本！
├── crates/                 # 仅在需要时
│   ├── core/
│   └── cli/
├── src/
│   ├── main.rs / lib.rs
│   ├── error.rs            # 统一错误类型（必做）
│   ├── config.rs           # 配置加载
│   └── ...
├── tests/                  # 集成测试
├── benches/                # 基准测试
├── migrations/             # 数据库迁移（如适用）
└── configuration/          # 环境配置文件

错误处理架构（生产级）

// ✅ 正确：统一 AppError + thiserror + 结构化错误码
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("IO 错误: {0}")]
    Io(#[from] std::io::Error),

    #[error("数据库错误: {0}")]
    Database(#[from] sqlx::Error),

    #[error("配置错误: {0}")]
    Config(String),

    #[error("未授权访问")]
    Unauthorized,

    #[error("资源不存在: {0}")]
    NotFound(String),

    #[error("上游服务不可用: {source}, service={service}")]
    Upstream {
        source: reqwest::Error,
        service: String,
    },
}

// 为序列化场景实现 Serialize（如 IPC/Web）
impl serde::Serialize for AppError {
    fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>
    where S: serde::Serializer {
        s.serialize_str(&self.to_string())
    }
}

⚠️ 致命反模式：不要在库代码中使用 anyhow —— 它不实现 Serialize。anyhow 仅用于 main.rs 和二进制入口。

并发与异步模式

异步运行时选择

生产环境反模式速查

死锁实战案例

// ❌ 致命反模式：看起来正确，但会在生产中死锁
use std::sync::Mutex;

pub struct OrderService {
    cache: Mutex<HashMap<OrderId, Order>>,
    repo: Arc<dyn OrderRepository>,
}

impl OrderService {
    pub async fn get_or_fetch(&self, id: OrderId) -> Result<Order, Error> {
        let mut cache = self.cache.lock().unwrap(); // 获取锁
        if let Some(order) = cache.get(&id) {
            return Ok(order.clone());
        }
        let order = self.repo.fetch(id).await?; // ← 跨 .await 持有锁！
        cache.insert(id, order.clone());
        Ok(order)
    }
}

// ✅ 正确：先释放锁，再 await
pub async fn get_or_fetch(&self, id: OrderId) -> Result<Order, Error> {
    if let Some(order) = self.cache.lock().unwrap().get(&id).cloned() {
        return Ok(order);
    }
    let order = self.repo.fetch(id).await?; // 无锁持有
    self.cache.lock().unwrap().insert(id, order.clone());
    Ok(order)
}

💡 Clippy 保护：在 clippy.toml 中启用 await-holding-lock lint：

await-holding-lock-timeout = 0

领域特定开发指导

A. CLI 工具开发

代表项目：ripgrep, fd, bat, eza, zoxide, just, starship, broot, zellij

技术栈模板：

[dependencies]
clap = { version = "4", features = ["derive"] }  # 参数解析
anyhow = "1"                                       # 错误处理（仅 binary）
tracing = "0.1"                                    # 结构化日志
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
tokio = { version = "1", features = ["full"] }     # 异步运行时
serde = { version = "1", features = ["derive"] }   # 序列化

架构要点：

• 使用 clap derive 模式定义命令行接口
• TUI 应用使用 ratatui（终端 UI 框架）
• 并行文件搜索参考 ripgrep 的 ignore crate + grep-searcher
• 使用 human-panic 设置友好的 panic 处理

B. Web 服务开发

框架选型：

axum 标准分层架构：

src/
├── main.rs              # 启动 + 路由注册
├── config.rs            # 配置（database_url, port...）
├── error.rs             # AppError 类型
├── state.rs             # AppState (共享状态)
├── routes/
│   ├── mod.rs
│   ├── health.rs        # GET /health
│   └── users.rs         # CRUD /users
├── handlers/            # 请求处理器（薄层）
│   └── mod.rs
├── services/            # 业务逻辑
│   └── mod.rs
└── repository/          # 数据访问
    └── mod.rs

中间件链最佳实践：

let app = Router::new()
    .route("/api/users", post(create_user))
    .layer(TraceLayer::new_for_http())                    // 请求追踪
    .layer(CompressionLayer::new())                       // 压缩
    .layer(CorsLayer::permissive())                       // CORS
    .layer(Extension(reqwest::Client::new()))             # 注入 HTTP 客户端
    .with_state(state);                                   // 共享状态

C. 桌面应用开发

Tauri v2 关键决策点：

• IPC 边界设计（见 tauri-skills）
• 权限最小原则（Capability → Permission → Scope）
• 前端框架自由选择（React/Vue/Svelte/Solid）

D. 嵌入式开发

核心技术栈：

embassy vs RTIC 选择：

no_std 黄金规则：

1. 没有 Box/Vec/String（除非启用 alloc）
2. panic = 死机（必须定义 #[panic_handler]）
3. 没有标准库 → 使用 core + alloc crate
4. 所有错误必须可 Sized（不能用 dyn Error）

E. 游戏开发

引擎选型：

Bevy ECS 核心模式：

// Component: 纯数据标记
#[derive(Component)]
struct Player;

#[derive(Component)]
struct Velocity(Vec3);

// System: 纯函数 + 查询
fn movement_system(
    mut query: Query<(&mut Transform, &Velocity), With<Player>>,
    time: Res<Time>,
) {
    for (mut transform, velocity) in &mut query {
        transform.translation += velocity.0 * time.delta_seconds();
    }
}

// Schedule: 系统执行顺序
app.add_systems(Update, (
    input_system,
    movement_system.after(input_system),
    collision_system.after(movement_system),
));

F. 区块链开发

Substrate pallet 模式：

#[pallet::config]
pub trait Config: frame_system::Config {
    type RuntimeEvent: From<Event<Self>> = Into<<Self as frame_system::Config>::RuntimeEvent>;
    type WeightInfo: WeightInfo;
}

#[pallet::pallet]
pub struct Pallet<T>(_);

#[pallet::call]
impl<T: Config> Pallet<T> {
    #[pallet::weight(<T as Config>::WeightInfo::do_something())]
    pub fn do_something(origin: OriginFor<T>) -> DispatchResult {
        let _who = ensure_signed(origin)?;
        Self::deposit_event(Event::SomethingStored(who));
        Ok(())
    }
}

性能优化优先级表

性能分析工具链

# 1. 基准测试
cargo bench --bench my_benchmark

# 2. CPU 性能分析
cargo instrument --release -g -- bench my_benchmark

# 3. 内存分析 (heap)
cargo install heaptrack
heaptrack target/release/my_binary

# 4. PGO (Profile-Guided Optimization)
RUSTFLAGS="-C profile-generate=/tmp/pgo-data" cargo build --release
./target/release/my-binary  # 运行典型工作负载
RUSTFLAGS="-C profile-use=/tmp/pgo-data" cargo build --release

发布与分发

Crates.io 发布清单

• Cargo.toml 元信息完整（description, license, keywords, categories）
• 文档示例通过 cargo doc 无警告
• cargo test + cargo clippy -- -D warnings 全部通过
• cargo audit 无已知安全漏洞
• 版本号遵循语义化规范
• CHANGELOG.md 记录变更

二进制分发

CI/CD 必要检查

# GitHub Actions 示例
- run: cargo fmt --check
- run: cargo clippy -- -D warnings
- run: cargo test
- run: cargo test --all-features
- run: cargo audit
- run: cargo deny check

反模式速查表（完整版）

子技能索引

以下子技能提供各主题的深度指导：

参考文档

• architecture.md — Rust 项目架构模式详解
• commands.md — Cargo/Rust 常用命令速查
• meta-cognition.md — Rust 学习元认知框架

注意事项

Edition / Toolchain 注意事项

• 以当前 stable 与项目 MSRV 为准，不要把临时特性写成默认前提
• 升级 edition 或 toolchain 前，先验证 cargo check、cargo clippy 和测试套件
• 若需要新语法或新 trait 行为，先确认 crate 的兼容边界，再决定是否采用

MSRV (最低支持版本)

• 始终在 Cargo.toml 中声明 rust-version
• 使用 cargo msrv 验证
• 不要盲目升级 MSRV，考虑下游兼容性

unsafe 使用准则

1. 最小作用域：将 unsafe 封装为安全的公开 API
2. 必须注释：每处 unsafe 块必须有 // SAFETY: 解释为何安全
3. 审查机制：unsafe 代码应经过额外 code review
4. Miri 检测：对含 unsafe 的代码运行 cargo miri test 发现 UB

依赖安全

# 定期审计
cargo audit          # 安全漏洞检测
cargo deny check     # 许可证合规 + 禁止列表
cargo tree -d        # 查看依赖树深度
cargo outdated       # 检查过时依赖