rust-project-setup

Rust 项目设置

逐步指导如何设置新的 Rust 项目，包括正确的配置、Lint 和 CI。

快速参考

主题	参考
Cargo.toml 配置、配置档、依赖项	references/cargo-config.md
工作区组织、成员布局、共享依赖项	references/workspace-layout.md
GitHub Actions CI、缓存、MSRV 检查	references/ci-setup.md
功能标志、条件编译、构建脚本	references/features-conditional.md
no_std 开发、嵌入式目标、交叉编译	references/no-std.md

新项目检查清单

1. 创建项目

# Binary
cargo init my-app

# Library
cargo init --lib my-lib

# Workspace (create Cargo.toml manually)
mkdir my-workspace && cd my-workspace

2. 配置 Cargo.toml

设置 edition、rust-version（MSRV）和元数据：

[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"

3. 设置 Lint

添加 clippy 和 rustfmt 配置：

# Cargo.toml
[lints.clippy]
all = { level = "deny", priority = 10 }
pedantic = { level = "warn", priority = 3 }

[lints.rust]
future-incompatible = "warn"
nonstandard_style = "deny"
# unsafe_op_in_unsafe_fn is deny-by-default in edition 2024 — no need to set it

Edition 2024 的默认 Lint：unsafe_op_in_unsafe_fn 默认设为 deny。unsafe fn 中的 unsafe 操作需要显式使用 unsafe {} 代码块。gen 关键字已保留——如需将其用作标识符，请使用 r#gen。

# rustfmt.toml
edition = "2024"
reorder_imports = true
imports_granularity = "Crate"
group_imports = "StdExternalCrate"

4. 配置构建配置档

[profile.release]
lto = true
codegen-units = 1
strip = true

5. 设置 CI

添加 GitHub Actions 工作流，用于执行 check、clippy、test 和 fmt。请参阅 references/ci-setup.md。

6. Cargo.lock 策略

• 二进制程序：提交 Cargo.lock（确保构建可复现）
• 库：不要提交 Cargo.lock（使用者会自行解析版本）
• 在库的 .gitignore 中添加：Cargo.lock

7. 文档设置

对于库 crate，启用文档 Lint：

// src/lib.rs
#![deny(missing_docs)]

临时禁用 Lint 时，优先使用 #[expect(lint)] 而非 #[allow(lint)]——当不再需要禁用时，它会发出警告：

#[expect(dead_code, reason = "used in next PR")]
fn upcoming_feature() {}

工作区与单个 crate

用途	适用情况
单个 crate	小型项目、CLI 工具、简单的库
工作区	多个相关 crate、共享依赖项、单独的编译目标

工作区通过在成员间共享依赖项和构建产物来缩短编译时间。

项目结构

二进制程序

my-app/
  Cargo.toml
  rustfmt.toml
  src/
    main.rs
    lib.rs      # separate logic from entry point
  tests/
    integration_test.rs

库

my-lib/
  Cargo.toml
  rustfmt.toml
  src/
    lib.rs
    module_a.rs
    module_b/
      mod.rs
      types.rs
  tests/
    api_test.rs
  examples/
    basic_usage.rs

工作区

my-workspace/
  Cargo.toml          # [workspace] definition
  rustfmt.toml        # shared formatting
  crates/
    core/             # shared types and logic
    api/              # HTTP server
    cli/              # command-line interface

依赖项最佳实践

• 二进制程序使用精确版本：serde = "=1.0.210"
• 库使用版本范围：serde = "1"
• 显式分组功能：tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
• 测试专用 crate 使用 [dev-dependencies]
• 使用 cargo tree 检查重复版本
• 运行 cargo audit 检查安全漏洞
• 使用 std::sync::LazyLock 替代 once_cell/lazy_static（自 Rust 1.80 起稳定）

Edition 2024 迁移说明

将现有项目迁移到 edition 2024 时：

• unsafe fn 函数体中的 unsafe 操作现在需要使用显式的 unsafe {} 代码块
• extern "C" {} 代码块必须写作 unsafe extern "C" {}
• #[no_mangle] 和 #[export_name] 必须改为 #[unsafe(no_mangle)] 和 #[unsafe(export_name)]
• gen 是保留关键字——将所有 gen 标识符改为 r#gen 或其他名称
• -> impl Trait 默认会捕获所有作用域内的生命周期；使用 + use<'a> 进行精确控制
• !（never 类型）会回退为 ! 而非 ()——检查 match 分支和发散表达式
• if let 和尾部表达式中的临时值会更早销毁——检查在这些位置持有锁或守卫的代码

运行 cargo fix --edition 可自动修复大多数机械性变更。

设置完成门槛

将这些作为清单完成后的客观通过条件，而不是非正式的“看起来完成了”。

1. 清单加载成功——在项目或工作区根目录运行 cargo metadata --format-version 1。**通过：**退出代码为 0，且输出列出了你的 crate（package name 与预期相符）。
2. Lint 和格式检查——运行 cargo clippy --all-targets（如果警告必须导致失败，则添加 -- -D warnings）和 cargo fmt --check。**通过：**在将 CI 视为权威依据之前，两者的退出代码均为 0。
3. CI 已配置——已提交你打算运行的工作流（参见 references/ci-setup.md）。**通过：**至少一次流水线运行成功完成 check、clippy、tests 和 fmt（或你定义的子集）。
4. 锁文件策略——**二进制 crate：**已提交 Cargo.lock（git ls-files Cargo.lock 输出 Cargo.lock）。**库 crate：**未跟踪 Cargo.lock（git ls-files Cargo.lock 输出为空，或该文件已加入 gitignore 且从未添加）。**通过：**索引符合该策略，且没有意外的 Cargo.lock 变更。

相关技能

• rust-best-practices — 惯用模式和 edition 2024 编码指南
• rust-code-review — 涵盖所有权、unsafe 和 trait 设计的代码审查