现代 Rust 专家

技能文档

---
name: majiayu000-modern-rust-expert
title: 现代 Rust 专家
category: 开发工具
description: 专家级 Rust 编码指导，基于 Rust 2024 版、严格 clippy 合规与「函数式但务实」的工程哲学，帮助编写前沿、惯用、高性能的 Rust 代码。当用户编写或重构 Rust 代码、修复 clippy 警告、设计模块或 crate 结构、询问 Rust 2024 新特性、异步模式或性能优化时触发。触发词：Rust、clippy、Rust 2024、异步编程。
---

# 现代 Rust 专家

在编写任何 Rust 代码时应用本技能：以 Rust Edition 2024（MSRV 1.85.0）为基线，保持严格的 clippy 合规，采用「函数式但务实」的哲学——优先不可变与纯函数，但为性能与可读性保留实用出口。

## 技能工作流

### 步骤1：确认工具链版本

- Edition 2024 要求 rustc ≥ 1.85.0。
- 先执行 `rustc --version` 检查版本；不满足时提示用户运行 `rustup update stable`。
- 若项目报错 `rust-version 1.83.0 is older than ... required by edition 2024`，在 `[workspace.package]` 中将 `rust-version = "1.85.0"`。

### 步骤2：使用 Edition 2024 特性编写代码

优先使用以下稳定特性（详见 [references/rust2024-features.md](references/rust2024-features.md)）：

1. **trait 中的 async fn**：直接在 trait 定义中使用 `async fn`，不再依赖 `async-trait` crate。
2. **RPITIT**：trait 方法返回 `impl Future`，替代 `Box<dyn Future>`，避免堆分配。
3. **let-else**：用模式匹配提前返回，简化错误处理。
4. **增强的 const 泛型与内联 const 表达式**：栈上分配、编译期计算。
5. **C 字符串字面量** `c"..."`：FFI 场景直接生成 `&'static CStr`。
6. **let 链**：在 `if`/`while` 中用 `&&` 组合多个模式条件。

注意：`gen` 块、TAIT、specialization 等仍属 nightly，稳定版代码中禁止使用。

### 步骤3：clippy 合规与修复

- 在工作区根 `Cargo.toml` 用 `[workspace.lints]` 统一配置 lint；`pedantic` 组必须设 `priority = -1`，避免与单项 lint 冲突；各 crate 以 `[lints] workspace = true` 继承。
- 库代码中禁止 `unwrap()`、`expect()`、`panic!()`、`todo!()`、`unimplemented!()`（clippy deny）；测试工具代码可用 `#[allow(clippy::expect_used)]` 并注明理由。
- 常见告警的处理方式（混合文档注释风格、文档反引号、`# Panics` 段、非 Debug 类型手写 `Debug`、通配导入、match 臂合并等）见 [references/clippy-guide.md](references/clippy-guide.md)。

### 步骤4：代码组织与文档

- 模块文档统一使用外部文档注释 `///`，避免 `//!` 与 `///` 混用。
- 文档中所有类型名、函数名、trait 名必须用反引号包裹；可能 panic 的函数必须有 `# Panics` 段，返回 `Result` 的函数应有 `# Errors` 段。
- 多 crate 项目：依赖统一放 `[workspace.dependencies]`，共享元数据放 `[workspace.package]`；注意 workspace 依赖不能声明 `optional`，可选性在各 crate 中声明。
- `rustfmt.toml` 仅使用稳定版配置项，`edition = "2024"`，避免 `imports_granularity`、`wrap_comments` 等 nightly 选项。

### 步骤5：测试与性能

- 单元测试放 `#[cfg(test)] mod tests`，异步测试用 `#[tokio::test]`；属性测试用 `proptest`。
- 优先静态分发（泛型）而非 trait 对象（`Box<dyn ...>`），利用零成本抽象；仅在需要运行时多态（插件、热替换）时用动态分发。
- 热路径上可用 `SmallVec` 等小集合优化，减少堆分配。

### 步骤6：提交前自查

```bash
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features
```

检查清单：

- [ ] 文档中类型名均有反引号
- [ ] 库代码无 `unwrap`/`panic`/`todo`
- [ ] 可能 panic 的函数有 `# Panics` 段
- [ ] 无通配导入（`use super::*`，测试代码除外）
- [ ] 非 `Debug` 类型已手写 `Debug` 实现
- [ ] 可 `const fn` 的函数已标 `const`
- [ ] 优先静态分发

## 设计哲学：函数式但务实

1. **不可变优先**：性能关键处允许 `&mut self`。
2. **纯函数优先**：副作用以「Effect 值」描述而非立即执行（如 reducer 返回 `Vec<Effect>`，由运行时统一执行）。
3. **组合优先**：保留实用的逃生舱口；为性能允许 reducer 就地修改状态，避免多余克隆。
4. **可读性高于理论纯粹性**；显式优于隐式；让非法状态不可表示。

当拿不准时：遵循现有代码模式，优先显式写法；clippy 报警通常有充分理由，先修复再考虑豁免；不确定时询问而不是猜测。

使用说明

# 现代 Rust 专家

专家级 Rust 编码指导：基于 Rust 2024 版与严格 clippy 合规，帮助你写出惯用、高性能、可维护的 Rust 代码。

## 使用

安装后，在编写或重构 Rust 代码、修复 clippy 警告时自动生效。例如：

```text
帮我把这个 trait 改成 Rust 2024 的 async fn 写法，并消除所有 clippy 警告
```

## 工作原理

技能内置 Rust Edition 2024 特性参考（trait async fn、RPITIT、let-else、let 链等）、clippy 配置与常见告警修复指南，以及提交前自查清单，按「版本检查 → 编写代码 → clippy 合规 → 组织与文档 → 测试与性能 → 提交自查」的工作流逐步指导编码。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。