cmochance Rust-Skill — Rust 编程方法论 / 路由 / 知识库
把 Rust 任务变成「先分类路由 → 看准则与用例 → 写出惯用代码 → cargo 验证」的可重复工作流。本 skill 是方法论 + 主题路由 + 三层知识库(规则/配方/用例),不是单纯的语法手册。
基础来源:架构借鉴自社区
actionbook/rust-skills(router-first + 认知分层 + error-code 索引)的思路,剥除了其过度工程部分(强制评估 hook、协商协议、成就游戏化);规则知识库逐字移植自leonardomso/rust-skills(MIT);配方/用例借鉴 Rust Cookbook(CC0)、Rust by Example(MIT/Apache)、设计模式书(MPL-2.0)。完整归属见仓库根NOTICE。
核心姿态(写 Rust 的判断,不是套话)
- 惯用优于聪明:优先标准库/生态既有惯用法(见
references/rules/),别为绕过借用检查器而clone()满天飞、unwrap()一把梭、Box<dyn Trait>兜底。每个"投机"写法都该问:有没有更地道的? - 类型表达约束:能让编译期拦住的错误,不留到运行期(newtype / typestate /
Result/ 穷尽 match)。 - 不确定就验证,别猜:API/trait/方法签名、crate 版本、宏展开、生命周期推断——不确定就
cargo check/cargo expand/ 查 docs.rs,别凭记忆编。区分「我以为能编过」与「cargo 真编过了」。 - 报错先定位再动手:编译/借用报错先查
references/error-codes.md路由到根因域,别盲目加&/clone/生命周期标注试错。 - 破坏性降级要先问:把
Result吞成unwrap、把强类型降成String、删?改 panic 等"图省事"的降级,默认不做;没有非破坏性等价写法时,停下来说明权衡。
工作方式
- 先路由:把任务对照
references/routing.md(问题层级 / 用户意图 / crate·工具链 三维),确定进哪个子域,再动手——不要「先写起来再说」。 - 看准则 + 用例:进对应子域概览文件,顺着它链到
references/rules/(地道写法 + 反模式对照)、references/recipes/(完成某任务的配方)、references/examples/(概念可跑示例)。照着 Good 写,拿 Bad 自查。 - 写:产出能编过、惯用、带必要测试的代码;不确定的签名/行为用
cargo check/expand/nextest当场验。 - 验证:
cargo fmt && cargo clippy && cargo test(或nextest)三连;改了 unsafe 加cargo miri test;性能改动给criterion/hyperfine数据,别口头说"更快了"。 - 路由没命中 → 别硬塞,向用户说明并提议(可查 docs.rs / 标准库文档 / 联网)。
路由速查(详表见 references/routing.md)
| 任务 | 进入 |
|---|---|
| 所有权/借用/生命周期/移动语义 | references/ownership-lifetimes.md |
| 智能指针/内部可变性(Box/Rc/Arc/Cell/RefCell) | ownership-lifetimes.md + rules/(mem-*) |
| 类型系统/trait/泛型/单态化/typestate | references/types-traits-generics.md |
| 错误处理(Result/Option/?/thiserror/anyhow) | references/error-handling.md |
| 并发/async/tokio/rayon/Send+Sync | references/concurrency-async.md |
| unsafe/裸指针/FFI/bindgen/miri | references/unsafe-ffi.md |
| 声明宏/过程宏(derive/attr/function-like) | references/macros.md |
| API 设计(builder/newtype/sealed/封装) | references/api-design.md |
| 性能/profiling/分配/zero-cost | references/performance.md |
| 测试(单元/集成/proptest/nextest/criterion) | references/testing.md |
| Cargo/workspace/feature/build/发布 | references/project-cargo.md |
| serde/序列化/自定义 (de)serialize | references/serde-data.md |
| tracing/log/metrics 可观测性 | references/observability.md |
| Web 后端(axum/actix/tower) | references/domain-web.md |
| CLI(clap/终端) | references/domain-cli.md |
| 嵌入式/no_std/裸机 | references/domain-embedded.md |
| WASM(wasm-bindgen/wasm32) | references/domain-wasm.md |
| 系统/网络编程(socket/IO/进程) | references/domain-systems.md |
| 编译/借用报错 E0xxx | references/error-codes.md → 对应域 |
references/ 索引(按需加载,别预载全部)
导航层
routing.md— 完整路由矩阵(问题层级 / 用户意图 / crate·工具链)+ 跨域路径error-codes.md— rustc 错误码(E0382/E0499/E0502/E0277/E0507…)→ 根因域速查toolchain-and-mcp.md— 工具目录(rustup/cargo/clippy/rustfmt/miri/nextest/expand/bacon)+ rust-analyzer LSP / docs MCP(opt-in)
概览/导航子域(每个:识别/核心要点/典型坑/关联 rules·recipes·examples/参考)
- 语言机制:
ownership-lifetimes.md、types-traits-generics.md、error-handling.md、concurrency-async.md、unsafe-ffi.md、macros.md - 工程设计:
api-design.md、performance.md、testing.md、project-cargo.md、observability.md、serde-data.md - 领域:
domain-web.md、domain-cli.md、domain-embedded.md、domain-wasm.md、domain-systems.md
知识库三层(高密度,按需读单文件)
rules/— 265 条习惯/反模式规则(26 类:own/mem/type/trait/async/err/api/test/perf/unsafe…)。每条 = 一句话准则 + Why + Bad/Good 对照。开工前查rules/_index.md找相关条目。recipes/— 任务配方("怎么用 Rust 做 X":读写文件/HTTP 客户端/JSON/并发管道/CLI 解析/数据库…),每条完整可跑。见recipes/_index.md。examples/— 概念可跑用例(逐个语言/标准库特性的最小示例),对照学习。见examples/_index.md。deep/— 设计模式书高保真移植(idioms/patterns/anti-patterns/refactoring,MPL-2.0 分文件 + notice)。概览不够时进这里。见deep/_index.md。templates/— Cargo 项目骨架 / error 类型 / bench / 集成测试 / CI 模板,可直接套。
完成清单(交付前自检)
- 代码
cargo check/clippy真过了(不是「应该能编」),clippy 无 warning(或显式#[allow]并说明) - 写法对照过
rules/:没有为绕借用检查器而无谓clone/unwrap/Box<dyn>;错误用?传播而非吞掉 - 公共 API 有 rustdoc(
///+# Errors/# Panics/# Safety段如适用),关键路径有测试 - 改了 unsafe →
cargo miri test过;性能结论 → 有criterion/hyperfine数据 - crate/版本/签名来自实际查证(docs.rs /
cargo doc),没猜;不确定处标了置信度 - (可选)把踩坑/可复用解法回写本地知识库