主题 / 语言
Rust 项目的工具链与 MSRV、Cargo.lock、rustfmt 与 Clippy、unsafe、错误处理、异步（Tokio）、tracing 日志、测试工具、cargo-deny、数据库访问与迁移工具、FFI 和 HTTP 框架怎么选、怎么写。
rust-toolchain.toml 固定到补丁版，带上 rustfmt、clippy；库用 Cargo.toml 的 rust-version 声明最低支持版本（MSRV），CI 在这个版本上实际跑一次。cargo fix --edition 迁移。cargo new 默认跟踪锁文件；应用的 CI 一律 --locked。库的锁文件不影响下游，所以库还要另跑一次用最新依赖的构建。cargo fmt --check、cargo clippy -- -D warnings 进 CI；lint 级别统一写在 Cargo.toml 的 [lints] / [workspace.lints] 表里。forbid；每个 unsafe 块写 // SAFETY:，由 Clippy 检查；改动 unsafe 要指定的人审，有条件就用 Miri 跑测试。unwrap / expect / panic。spawn_blocking 或 Rayon；同步锁不跨 .await；channel 有界；外部调用都有超时；tokio::spawn 不是持久任务。cargo test --doc；并发原语用 loom，解析器用 proptest / cargo-fuzz，快照差异由人审。deny.toml 入库。sqlx migrate）、serde、thiserror / anyhow、tracing、clap。async-std 已停止维护，serde_yaml 已弃用，都不要用。channel 是完整的补丁版本号而不是 stable；构建日志打印 rustc -V 与之对照stable 时，不同机器、不同日期会用不同编译器构建，Clippy 新增的告警也会让 CI 无故变红。rustfmt、clippy；交叉编译用到的 target 也写进 targets。cargo hack check --rust-version），失败即阻断rust-version。rust-version 选依赖版本，声明准确才有用。rust-version 变化时，要求 PR 描述和变更日志里有对应说明MSRV 政策（例如「最近 N 个 stable」）写进 README；N 由项目自定，没有官方统一要求。
edition 字段；迁移 PR 里只含 edition 相关改动当前最新为 2024 edition，需要 Rust 1.85 及以后。Agent 和贡献者不要顺手改 edition、rust-version 或 target。
cargo build、cargo test、cargo clippy 命令带 --locked，锁文件需要变化时失败cargo install 默认忽略锁文件；发布可安装的命令行工具时，文档里写 cargo install --locked。
cargo update 再构建测试，失败时提醒cargo new 默认跟踪锁文件，但库的锁文件不影响下游用户，只锁住自己的 CI 会掩盖下游会遇到的问题。*；git 依赖必须固定 rev；依赖只能来自批准的 registry 或镜像[sources] 只允许批准的 registry 和 git 地址，[bans] 设 wildcards = "deny"* 和分支 HEAD 会在不知情时引入任意新代码，是供应链攻击的入口；crates.io 本身也拒绝发布通配版本依赖。cargo tree -e features 查看实际启用的 feature，用 cargo-machete 等工具找未使用的依赖cargo fmt --all -- --checkcargo clippy --all-targets --locked -- -D warnings，不得有告警--all-features不得在 crate 根写 #![allow(warnings)] 或整组关闭 clippy::correctness。
lints.workspace = true 继承#![deny(...)]示例：
[workspace.lints.rust]
unsafe_code = "forbid" # 需要 unsafe 的 crate 单独放宽
[workspace.lints.clippy]
undocumented_unsafe_blocks = "deny"
unwrap_used = "warn"
expect_used = "warn"
dbg_macro = "warn"
配合 CI 的 -D warnings，warn 实际也会阻断；希望只提示不阻断的 lint 不要放进来。
pedantic = "deny" 之类的写法#[expect(lint, reason = "...")]，不用不带理由的 #[allow]allow_attributes_without_reason（和 allow_attributes）检查unsafe_code = "forbid"；需要的 unsafe 集中在少数模块，并对外提供安全的接口unsafe_code；CI 用 grep 或 cargo-geiger 统计 unsafe 出现的位置// SAFETY: 注释，说明满足了哪些前提；每个 unsafe fn 写 # Safety 文档说明调用方要满足的前提undocumented_unsafe_blocks 和 missing_safety_doc 设为 deny；unsafe_op_in_unsafe_fn 不得放宽2024 edition 起 unsafe_op_in_unsafe_fn 默认告警：unsafe fn 体内的不安全操作也要写在显式的 unsafe {} 块里。
unsafe 时打标签并要求指定评审人；集中放 unsafe 的模块写进 CODEOWNERScargo miri test（可只跑相关模块）Miri 不支持 FFI 调用和部分系统调用，这类测试要跳过；跳过的部分改用 sanitizer。
std::error::Error，用 #[source] 保留底层原因；对外可能新增变体的枚举加 #[non_exhaustive]。.context(...) 补上下文。unwrap_used、expect_used、panic；clippy.toml 设 allow-unwrap-in-tests = true、allow-expect-in-tests = true 豁免测试；剩下的用 #[expect(..., reason = "...")] 逐处说明真正不可能失败的地方（如编译期常量的正则）可以 expect，在消息里写清为什么不会失败。
# Panics 和 # Errors 小节missing_panics_doc、missing_errors_docstd::fs、std::thread::sleep、同步数据库驱动、重计算循环；压测时用 tokio-console 或 tracing 的耗时数据找长时间不让出的任务.await 期间持有 std 或 parking_lot 的同步锁await_holding_lock、await_holding_refcell_ref 设为 deny先缩小临界区、在 await 前释放；确实要跨 await 持有时用 tokio::sync::Mutex。
unbounded_channel，评审时确认理由tokio::spawn 的 JoinHandle 是否被持有或交给任务组；停机路径有取消信号（如 CancellationToken）需要可靠执行、可重试的工作放进持久化的任务队列或 outbox（见 17、18）。在 tokio::select! 里使用的 future 要确认是否取消安全。
reqwest::Client::builder() 是否设置了 timeout、connect_timeout；其他调用用 tokio::time::timeout 包裹；故障注入测试验证tracing_subscriber 的初始化调用、没有 println! / eprintln! 打日志（Clippy 的 print_stdout、print_stderr）tracing-subscriber 输出 JSON；需要跨服务追踪时接 OpenTelemetry（见 26）。#[instrument(skip(...))] 时跳过大参数和敏感参数。#[derive(Debug)]；日志测试断言输出里没有测试密钥；密钥扫描见 25cargo test --doccargo nextest run --locked 和 cargo test --doc --locked 两步std::sync::atomic 实现同步逻辑的模块是否有 loom 测试INSTA_UPDATE=no（或使用 cargo insta test --check），快照不一致即失败；快照文件改动在 PR 里单独评审cargo deny check，非零退出即失败；忽略某条公告时在 deny.toml 写明理由和复查日期cargo build --release --locked --offline 验证能离线构建不等于能离线运行，运行层的验收见 26。
query! 宏或 .bind()），不用 format! 拼接用户输入sqlx::query / query_as 的 format! 结果；动态拼接的标识符只能来自白名单cargo sqlx prepare --checkcargo sqlx prepare --check；构建时不设 DATABASE_URL，确认走的是离线缓存设了 DATABASE_URL 时宏仍会尝试连接数据库，CI 的离线构建步骤要确保它没被设置。
sqlx migrate）执行；迁移原则按 17extern "C"；跨边界的类型用 #[repr(C)]，不直接传 String、Vec 或普通 Rust 结构体improper_ctypes、improper_ctypes_definitions 不得放宽；评审时检查每个导出函数是否用 catch_unwind 兜住 panic 或明确使用 extern "C-unwind"extern 块要写成 unsafe extern，no_mangle 等属性要写成 #[unsafe(no_mangle)]。升级绑定库时，按目标语言版本和平台矩阵重新测试，不能只看 Rust 侧能否编译。
cargo semver-checks，发现破坏性变化而版本号未相应递增时失败没有符合条件的规则。
| 类别 | 默认 | 备选（何时用） | 不推荐 |
|---|---|---|---|
| 工具链管理 | rustup + 仓库根目录的 rust-toolchain.toml | Nix 或 mise（一台机器上要统一管理多种语言和系统依赖） | 系统包管理器自带的 rustc：版本滞后、不好切换，组件和 target 不全 |
| lint 配置 | Cargo.toml 的 [lints] / [workspace.lints] 表 + clippy.toml（只放 lint 的参数） | — | 在每个 crate 根写一串 #![deny(...)]：分散、难统一修改 |
| 异步运行时 | Tokio · Tokio 为 MIT 网络服务和需要异步 I/O 的程序；纯 CPU 计算或简单的同步命令行工具不引入异步运行时 | smol（想要更小的运行时，且用到的库不依赖 Tokio） | async-std：官方已宣布停止维护，建议迁移到 smol |
| HTTP 服务框架 | Axum + tower / tower-http 中间件 · Axum 为 MIT | Actix Web（团队已熟悉，或已有 Actix 代码） tonic（提供 gRPC 接口） | 普通业务服务直接基于 hyper 自己搭：路由、提取器、中间件都要自己写，Axum 已在 hyper 之上做好 |
| HTTP 客户端 | reqwest（进程内复用一个 Client，设好超时） | hyper 客户端（需要极细的连接控制，或写底层库） | 每个请求新建 Client：丢掉连接池，增加握手开销 |
| 数据库访问 | SQLx（以 SQL 为准，编译期检查查询） · SQLx 为 MIT OR Apache-2.0 | SeaORM（增删改查多、需要动态组装查询） Diesel（想要强类型的查询构建器，接受同步接口或配合 diesel-async） tokio-postgres + deadpool-postgres（只用 PostgreSQL、需要驱动层的细粒度控制） | 同一项目混用多套数据库访问库：事务、连接池、错误处理各成一套 |
| 数据库迁移工具 | sqlx-cli（sqlx migrate），迁移文件放 migrations/ 入库使用 SQLx 的项目；迁移原则见 17 | sea-orm-migration（使用 SeaORM） diesel_migrations（使用 Diesel） | 在应用启动代码里手写 DDL：多副本同时执行、没有记录、无法审查 |
| 错误处理 | 库用 thiserror 定义错误枚举；应用入口用 anyhow | snafu（需要大量带结构化上下文的错误；同一模块不和 thiserror 混用） | 到处 unwrap，或把所有错误转成 String：失败时没有类型可分支、没有上下文可查 |
| 日志与追踪 | tracing + tracing-subscriber（服务输出 JSON） | log + env_logger（很小的命令行工具，不需要 span） tracing-opentelemetry（需要跨服务追踪（见 26）） | println! / eprintln! 当日志：没有级别、没有结构，无法收集 |
| 测试执行 | cargo-nextest + cargo test --doc | 只用 cargo test（测试很少、不在乎速度和隔离） | — |
| 进阶测试 | proptest（属性测试）、cargo-fuzz（模糊测试）、loom（并发交错）、Miri（未定义行为）、insta（快照） | — | — |
| 依赖审计 | cargo-deny · cargo-deny 为 MIT OR Apache-2.0；作为 CI 里独立运行的工具使用 | cargo-audit（只需要漏洞检查，或要用它的 cargo audit fix 等功能） | — |
| 序列化 | serde + serde_json | — | serde_yaml：作者已标为弃用、不再维护；YAML 的替代库见待确认 |
| 命令行参数 | clap（derive 写法） | argh、lexopt（很在意二进制体积和编译时间） | — |
| 跨语言绑定 | C/C++ 用 cxx 或最薄的 extern "C"；Python 用 PyO3 + maturin；Node 用 napi-rs；浏览器用 wasm-bindgen | — | 把 Rust 结构体的内存布局直接当 C ABI：布局不稳定，析构和 panic 都无法跨边界 |
| 交叉编译 | 优先用目标架构的原生构建机；不行再用 rustup target + cross | cargo-zigbuild（需要指定 glibc 版本，或不想依赖容器） | 以为加 --target 就能解决原生依赖：OpenSSL 等 C 库要对应 target 的工具链和 sysroot |
#![deny(...)]sqlx migrate），迁移文件放 migrations/ 入库cargo test --doccargo audit fix 等功能）extern "C"；Python 用 PyO3 + maturin；Node 用 napi-rs；浏览器用 wasm-bindgen--target 就能解决原生依赖channel = "stable"git = "...", branch = "main"rev，并在 cargo-deny 里登记来源'static、Box::leak 或到处 Arc<Mutex<T>>Arc<T>，可变状态优先用消息传递spawn_blocking、Rayon，或拆成独立服务tokio::spawn 发邮件、写审计当作可靠的后台任务cargo nextest run，文档示例早就编不过了cargo test --doccargo insta accept 一键接受所有快照差异#![allow(warnings)]#[expect(..., reason = "...")]下面的内容还没核实或待补调研，不要当成规则执行。
global-min-publish-age，且不约束 cargo install）、[lints.cargo] 未使用依赖诊断、never type；联网检索只找到间接提及，未找到正式发布说明，暂不写成规则，核实后再考虑加入「建议开启冷却」