rust-review

Rust 代码审查

依据 rust-best-practices 技能编写代码时遵循的同一套规则审查 Rust 代码，并报告需要修改的内容。输出应为审查意见，而非重写代码：由读者决定要修复什么。只有用户提出要求时，才重写代码。

1. 确定范围

• 阅读内容。 严格审查用户指定的内容：文件、模块、crate 或差异。对于差异，审查已更改的行及其引发的问题，而不是整个文件。
• 库还是应用程序。 检查是否存在 lib.rs、被其他 crate 使用的 pub 项，或已发布的 Cargo.toml。库代码必须严格遵循 API 设计规则。应用程序代码则遵循简洁性规则：使用具体类型、采用 anyhow 风格的错误处理，且不做推测性泛化。在报告开头说明你采用了哪种假设。
• edition 和 MSRV。 从 Cargo.toml 中确认，以免建议使用项目无法采用的功能。

2. 如果可以，先运行工具

如果有可用的 Rust 工具链，请在 crate 根目录运行以下命令，并将结果纳入报告。这些工具能发现机械性问题，让你可以专注于设计。

cargo fmt --check
cargo clippy --all-targets --all-features -- -W clippy::pedantic
cargo test

不要粘贴原始的 clippy 输出。将重复的警告归为一条问题，并跳过与此代码无关的 pedantic lint。如果无法使用这些工具，请在报告中说明，并通过阅读代码进行审查。

3. 按优先级检查的内容

按以下顺序检查。前两类问题中藏着真正的 bug。

正确性与健全性

• 未定义行为：没有 // SAFETY: 注释的 unsafe 代码块；使用 transmute 转换枚举或延长生命周期；用 unsafe impl Send/Sync 来绕过编译器检查；或安全函数可通过安全调用导致未定义行为（不健全）。
• 可触达路径上的 panic：任何外部输入可能触及的地方，都要检查 unwrap()、expect()、索引操作、会回绕的 as 转换或整数溢出。
• Trait 契约：手写的 Ord 配合派生的 PartialEq，或与 Eq 不一致的 Hash。这些会悄无声息地破坏 BTreeMap、HashMap、sort 和 dedup。
• 锁的隐患：持有 MutexGuard 跨越 .await 或将其返回给调用者；在锁内调用用户闭包；或使用 into_inner 恢复中毒的锁。
• 会 panic、阻塞或可能失败的析构函数。

错误处理

• 调用者无法利用的错误：将 ()、String 或 Box<dyn Error> 用作库的公开错误类型；没有 Display 和 std::error::Error 的错误枚举；或在库的公开 API 中使用 anyhow::Error。
• 丢失信息的错误：map_err(|_| ...)、没有 source()，或错误消息未包含失败的路径、行号或值。
• 用 panic 处理预期会发生的失败，或将 catch_unwind 用作控制流。

API 设计（对库严格要求）

• 参数：用 &String、&Vec<T> 或 &Box<T>，而不是 &str、&[T] 或 &T；公开签名中包含 bool 参数；接管所有权后又克隆，或在内部克隆借用值以获取所有权。
• 可见性：应设为私有的公开字段；在公开签名中使用 Rc、RefCell 或 Arc；或让第三方类型泄漏到 API 中。
• 缺少标准 Trait：公开类型缺少 Debug，错误类型缺少 Display，无参 new() 旁缺少 Default，以及使用临时的 from_str 方法而不是 FromStr。
• 命名：getter 使用 get_ 前缀；as_/to_/into_ 与其成本和所有权语义不符；以及使用 Manager/Service/Util 这类名称。
• 演进性：应标记为 #[non_exhaustive] 的公开枚举或结构体，或应封闭的 Trait。

惯用写法与清晰度

• 仅为满足借用检查器而存在的克隆。
• 先检查再解包（if x.is_some() { x.unwrap() }）；本可使用组合器表达得更清晰却使用了 match，或反之。
• 使用 + 拼接字符串；手写循环本可用迭代器表达得更清晰；或迭代器链过长，本应用循环。
• HashMap 的迭代顺序泄漏到输出或测试中。
• 在源码中使用 #![deny(warnings)]；没有理由的 #[allow]；以及对外部 crate 使用 glob 导入。

文档与测试

• 公开项缺少文档，或文档只是重复名称。
• 适用时缺少 # Errors、# Panics 或 # Safety 章节。
• 文档示例使用 unwrap() 而不是 ?。
• 逻辑没有测试，或测试只是重复常量。

rust-best-practices 技能及其 references/ 文件夹包含完整规则和理由。如果已安装，请在某项发现涉及不确定的规则时阅读相关参考资料。否则，请依据上述摘要。

4. 撰写报告

使用以下结构：

# Rust review: <what was reviewed>

<One paragraph: what the code does, library or application, overall verdict, and the
single most important thing to fix. Say whether clippy and tests were run.>

## Must fix
### 1. <Short title> (`src/file.rs:42`)
**Rule:** <rule name and source, e.g. "Errors implement std::error::Error (C-GOOD-ERR,
Rust API Guidelines)">
**Problem:** <what is wrong and the concrete consequence, one or two sentences>
**Fix:**
```rust
<the smallest code change that fixes it>
```

## Should fix
### 2. ...

## Consider
### 3. ...

## What's already good
- <2 to 4 specific things the code does well>

如何对发现的问题排序：

• 必须修复表示存在 bug、健全性漏洞、可触发的 panic，或发布后会成为破坏性变更的 API 错误。
• 应该修复表示功能可用，但违反了会造成实际代价的规则，例如错误消息更差、测试更难，或 API 令人困惑。
• 可以考虑表示风格、命名和润色方面的问题。

每项发现的规则：

• 注明位置：每项发现都要注明 file:line；若没有具体位置（例如缺少测试），则注明 whole file。还要注明规则及其来源：API Guidelines 代码（如 C-GETTER）、Effective Rust 条目编号、Microsoft 指南代码（如 M-PANIC-ON-BUG）、clippy lint 名称，或 "Google Rust Style Guide"。读者应该能够查找到该规则。
• 以代码展示修复方式，并且只保留需要修改的行。不要重写整个函数。
• 合并重复项。 对于“解析结果上有八处 unwrap() 调用”，列出这些行，作为一项发现，而不是八项。
• 尊重原意。 如果某项看起来是有意为之，例如有文档说明的特例或解释缘由的注释，请在“可以考虑”中说明及其权衡。不要将其标为必须修复。
• 把握分寸。 对于短文件，列出五到十项发现就足够了。不要凑数，也不要把真正的 bug 混在风格问题中。
• 必须包含“已有亮点”。 这能告诉作者哪些内容值得保留，也能让其余建议更可信。

5. 提供 lint 建议

如果项目没有 [lints] 表格，请在报告末尾建议使用 BeautifulRust lint 配置（BeautifulRust 仓库中的 lints/lints.toml 和 lints/clippy.toml，https://github.com/morganlinton/BeautifulRust）。它可以让 clippy 自动发现上述大多数机械性问题。请指出本次审查中它能发现的两到三项问题。