02 工具链与 Cargo 工作流（你每天会用到的命令）

本章目标

  • 你能熟练使用 Cargo 完成开发闭环：编译、运行、检查、格式化、静态检查、测试。
  • 你能读懂 Cargo.toml / Cargo.lock，知道依赖和 feature 怎么影响编译。
  • 你能把“工具链”变成肌肉记忆，让学习 Rust 不被环境问题消耗。

必备工具（建议安装/开启）

  • Rust toolchain：rustup / cargo / rustc
  • IDE：VS Code + rust-analyzer（或 JetBrains Rust）
  • 格式化：rustfmt
  • 静态检查：clippy

rustfmt / clippy 通常随 toolchain 安装，但可能需要 rustup component add rustfmt clippy。

Cargo 常用命令（按使用频率排序）

1) cargo check

  • 只做类型检查，不产物最终二进制，速度快，适合频繁运行。
  • 你写 Rust 的大多数错误，cargo check 都能第一时间告诉你。

2) cargo run

  • 编译并运行当前 crate 的二进制（本项目会启动 Dioxus 桌面应用）。
  • 常用参数：
    • cargo run --release：发布模式（优化后更快，但编译更慢）

3) cargo build

  • 只编译不运行。
  • 常用于 CI 或你想确认产物可生成。

4) cargo fmt

  • 使用 rustfmt 自动格式化。
  • 建议开启 IDE 保存时自动格式化，减少风格讨论成本。

5) cargo clippy

  • Clippy 是“更严格”的 lint 工具，会给出很多“更 Rust”的建议。
  • 你学习期非常适合用它纠正习惯（比如不必要的 clone、低效写法、可读性问题）。

6) cargo test

  • 跑单元测试与集成测试。
  • 本项目目前测试较少，但你可以把练习写成测试（学习效果很好）。

依赖与锁文件：Cargo.toml vs Cargo.lock

  • Cargo.toml：你声明“我需要什么依赖”
  • Cargo.lock：Cargo 解析出的“我实际用的版本”（确保可复现构建）

在 asset-light 中，依赖定义见 Cargo.toml：

  • dioxus：UI 框架（desktop + router feature）
  • rusqlite：SQLite 访问（bundled feature 便于本地开发）
  • serde：序列化
  • chrono：时间
  • uuid：唯一 ID
  • rust_decimal：金额/比例的精确计算
  • thiserror：更优雅的错误类型（当前代码仍有进一步统一空间）

本项目开发中“最常用”的命令组合

开发循环（最推荐）

  1. cargo fmt
  2. cargo check
  3. cargo run

只验证质量（更严格）

  1. cargo fmt
  2. cargo clippy
  3. cargo test

环境变量（对调试非常有用）

1) ASSET_LIGHT_DB_PATH

用于指定 sqlite 文件路径，常用于：

  • 临时跑一个干净的 DB
  • 做手工验证而不污染真实数据
  • 写测试时使用临时目录

实现位置：src/db/connection.rs → Database::db_path()

常见坑与解决思路

1) 第一次编译下载依赖很慢/失败

  • 第一次 cargo build / cargo run 会下载 crates。
  • 如果网络环境不稳定，会出现解析/下载失败。

建议：

  • 先确保能访问 crates.io（必要时配置代理）
  • 尽量让构建机/CI 具备稳定网络

2) 你改了很多文件，cargo run 很慢

  • 先用 cargo check 快速拿到类型错误反馈
  • 修到 cargo check 通过后再 cargo run

3) “跑起来了但看不到数据”

这是本地 app 常见问题：

  • 数据存在 DB 文件里，换了 DB 路径相当于换了数据源
  • 或者迁移逻辑做了破坏性升级（清空数据）

排查：

  • 是否设置了 ASSET_LIGHT_DB_PATH？
  • src/db/connection.rs 的迁移逻辑是否 drop 过表？

本章练习（把工具链练熟）

  1. 运行一次 cargo fmt，观察有哪些文件被格式化。
  2. 运行一次 cargo check，熟悉输出结构（警告/错误定位方式）。
  3. 用一个临时 DB 路径启动应用：
ASSET_LIGHT_DB_PATH=/tmp/asset-light-dev.db cargo run

然后在 UI 里新增资产，确认重新启动后数据仍存在该 DB 文件中。