Rust 开发规范 Skill

为 Rust 代码审查、架构设计、crate 开发提供系统化规范检查与建议。

触发条件

当开发者提出以下类型的问题时，自动加载本 Skill：

「这段代码符合 Rust 惯用法吗？」
「帮我设计一个 Rust crate 的项目结构」
「这个错误类型设计合理吗？」
「如何为这个库写测试 / 基准测试？」
「异步代码有没有常见陷阱？」
「这个类型命名是否符合 Rust 约定？」
「如何把现有代码迁移到 async/.await？」
「WASM / 嵌入式 / no_std 有什么要注意的？」
粘贴 Rust 代码片段请求审查或修复
涉及 Cargo.toml 配置、crate 依赖管理
涉及 tokio、async-std、serde、thiserror、anyhow 等 Rust 生态 crate
遇到 Rust 编译错误、panic、lifetime / borrow checker 问题
讨论 TCP / QUIC 网络编程、通道模式、内存分配器调优

核心规范速查

命名约定（RFC 430）

| 条目 | 约定 | |------|------| | 类型 / trait / enum 变体 | UpperCamelCase | | 函数 / 方法 / 模块 / 宏 | snake_case | | 常量 / 静态 | SCREAMING_SNAKE_CASE | | Crate 名 | snake_case（无 -rs 后缀） |

详细规则 → references/naming-conventions.md

错误处理

库 crate：用 thiserror 精确定义错误类型
应用 crate：用 anyhow 附带上下文
不用 unwrap() 处理外部输入；用 ? 或 match
详细规则 → references/error-handling.md

项目结构

.
├── Cargo.toml
├── src/
│   ├── lib.rs / main.rs
│   └── bin/        # 额外二进制
├── benches/         # 基准测试
├── examples/        # 示例
└── tests/           # 集成测试

详细规则 → references/project-structure.md

测试与基准

单元测试：#[cfg(test)] mod tests
集成测试：tests/*.rs
基准测试：criterion（稳定版）或 cargo bench（nightly）
属性测试：proptest
详细规则 → references/testing-benchmarking.md

异步编程

用 #[tokio::main] 或 #[async-std::main]
耗时同步操作必须用 tokio::task::spawn_blocking
不要用 std::sync::Mutex（会阻塞），用 tokio::sync::Mutex
详细规则 → references/async-embedded-wasm.md

无分支编程（CPU 分支预测优化）

当 perf / flamegraph 定位到热循环，且数据分布不可预测时，分支预测失败可能是瓶颈
把控制依赖改写为数据依赖：out[n] = x; n += (cond) as usize; out.truncate(n);
编译器会生成 seta 指令，无分支、无跳转、无预测失败；最坏情况可提速约 4 倍
不要提前优化：先做「排序 vs 随机」基准对比确认瓶颈，且分支体要很小
详细规则 → references/branchless-programming.md

新语法特性（Rust 2024+）

let-else：解构可失败模式，匹配失败则发散（return/break/panic）
let chains：if/while 中链式 let 条件（Edition 2024）
async closures：async || {} 异步闭包，可借用捕获
gen blocks：生成器块，产出惰性迭代器（nightly）
LazyLock/LazyCell：标准库懒加载，替代 lazy_static!
unsafe extern blocks、unsafe attributes、RPIT lifetime capture rules
详细规则 → references/new-syntax.md

嵌入式 / no_std

#![no_std] + panic_handler
避免堆分配，用 heapless crate
日志用 defmt（编译时格式化）
详细规则 → references/async-embedded-wasm.md

WASM

wasm-pack build --target web/nodejs/bundler
导出函数用 #[wasm_bindgen]
字符串转换有开销，优先传 &[u8] / ArrayBuffer
详细规则 → references/async-embedded-wasm.md

参考资源

| 文件 | 内容 | |------|------| | references/naming-conventions.md | RFC 430 命名规范（CamelCase / snake_case / 转换方法前缀） | | references/project-structure.md | Cargo 项目布局、Workspace 组织、条件编译 | | references/error-handling.md | panic! / Result / ? / thiserror / anyhow | | references/testing-benchmarking.md | 单元测试、集成测试、criterion 基准、proptest 属性测试 | | references/async-embedded-wasm.md | 异步编程陷阱、嵌入式 no_std、WASM 绑定 | | references/networking-tcp-quic.md | TCP 异步编程、QUIC（quinn）实战 | | references/tokio-channel-patterns.md | Tokio mpsc 通道内存模型与选型建议 | | references/phantomdata-zst.md | PhantomData 与零大小类型的正确使用 | | references/async-future-bloat.md | Async Future 编译器膨胀问题与优化 | | references/async-future-design.md | Rust Future 手动 poll 设计哲学 | | references/mimalloc-tuning.md | Mimalloc 分配器调优与参数配置 | | references/branchless-programming.md | 无分支编程与 CPU 分支预测优化（热循环提速 4 倍实战） | | references/new-syntax.md | Rust 2024+ 新语法（let-else / let chains / async closures / gen blocks / LazyLock） | | references/effective-rust.md | Effective Rust 35 条核心准则（O'Reilly） |

使用方式

代码审查：粘贴 Rust 代码片段，询问「这段是否符合规范？」
架构设计：描述需求（如「一个 TCP 服务器，需要处理 10K 并发连接」），获取建议
学习路径：询问「如何学习 Rust 异步编程？」，获取结构化学习资源
调试帮助：粘贴错误信息或 panic 栈，获取诊断和修复建议

与外部资源的关系

Rust 官方文档：https://doc.rust-lang.org/
Rust API Guidelines：https://rust-lang.github.io/api-guidelines/
Tokio 文档：https://docs.rs/tokio/
Async Book：https://rust-lang.github.io/async-book/
Embedded Book：https://rust-embedded.github.io/book/
WASM Book：https://rustwasm.github.io/docs/book/
Effective Rust：https://lurklurk.org/effective-rust/

技术来源

本 Skill 综合以下来源：

Rust RFC 430（命名约定）
Rust API Guidelines（接口设计）
《Effective Rust》（David Drysdale，O'Reilly）
微信公众号技术文章（黑咖不黑、编程笔记、写代码的架构师、雪橇车嘚耶）
微信公众号《Rust开发笔记》：Rust 无分支编程与 CPU 分支预测优化
Rust 官方文档与社区最佳实践

版本

创建日期：2026-06-16
最后更新：2026-09-04
版本：v1.4（新增 Rust 2024+ 新语法特性参考）