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

嵌入式 / 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/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 官方文档与社区最佳实践

版本

创建日期：2026-06-16
最后更新：2026-07-23
版本：v1.2（补 frontmatter + 触发条件优化）