BeautifulRust:Rust 设计与可维护性规则提取
来源:morganlinton/BeautifulRust(原始出处:https://github.com/morganlinton/BeautifulRust);固定提交 b9718436d77ee7bcf17cdcb6aa27628feb95d97a;提取日期:2026-11-12。
这是中文归纳和语义校正,不是原文逐字翻译,也不包含原 skill 的执行编排。原始文件可通过每条规则的链接查看;改写说明和许可见 README。
基于 skills/rust-review/SKILL.md 和 skills/rust-best-practices/SKILL.md 的通用 Rust 部分。B-* 是本次提取编号;不是上游原生规则 ID。Bevy/ECS、跨语言迁移 skill 和完整 lint 配置不纳入本次 IDPS 合并规则。
| ID | 上游章节 | 核查内容 | 原文 |
|---|---|---|---|
B-01 | 1. Mindset | 区分库与应用:库重视稳定、可组合的 API,应用优先直接具体的实现,避免为了潜在复用提前抽象。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-02 | 2. Before you hand back code | 格式、lint、测试由工具完成;用项目既有工具链/feature 组合,报告真实运行结果。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-03 | 2. Before you hand back code | lint 抑制范围最小且有理由;适用时使用 expect(lint) 暴露过期抑制;warnings-as-errors 放到受控 CI 中。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-04 | 3. Ownership and borrowing | 独占/共享所有权有明确设计;不为借用检查盲目复制,考虑缩短借用、take/replace 和数据结构拆分。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-05 | 3. Ownership and borrowing | 参数按只读/修改/保存选择借用、可变借用或按值传递;不要接收借用后无故克隆。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-06 | 3. Ownership and borrowing | &str、&[T] 等宽泛借用参数提高可用性;不要把 Rc/RefCell/Arc 等实现细节无理由固定到公共接口。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-07 | 4. Types and API design | 用 enum、newtype、Option、Path/Duration 表达领域约束;构造时验证,不以哨兵值和含义不明 bool 隐藏状态。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-08 | 4. Types and API design | 转换命名表达成本与所有权;按约定实现 From/TryFrom/FromStr/Display 等标准 trait。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-09 | 4. Types and API design | 公共类型按语义实现 Debug、Clone、Default 等;敏感值 Debug 脱敏,独占资源/密钥不盲目 Clone/Copy。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-10 | 4. Types and API design | Eq、Ord、PartialOrd、Hash 必须语义一致;手写与 derive 可以共存,但不能比较不同的等价关系。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-11 | 4. Types and API design | 复杂构造集中处理跨字段校验,必要时 builder;new 和 Default 的契约一致,不强行给无合理默认值的类型加 Default。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-12 | 4. Types and API design | 默认收紧可见性,评估 non_exhaustive、sealed trait 和第三方类型泄漏对未来演进的影响,兼容现有调用者。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-13 | 4. Types and API design | 泛型、dyn、宏和 trait 由需求驱动;应用代码避免层层抽象,借用/返回集合按调用方需要选择。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-14 | 4. Types and API design | 重构保持公开行为、协议字节和失败语义;不理解的兼容行为先调查,改签名需列出迁移影响。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-15 | 5. Errors and panics | 正常缺失用 Option,可处理失败用 Result;不得用 panic 处理外部坏输入或把 catch_unwind 当普通异常机制。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-16 | 5. Errors and panics | 库的错误可被匹配、显示并保留 source;应用用 anyhow/eyre 加上下文;使用哪个错误库服从项目约定。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-17 | 5. Errors and panics | 析构尽量不失败、不阻塞、不 panic;重要且可失败的关闭提供显式 close/finish 并检查结果。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-18 | 6. Everyday idioms | 组合器、迭代器与显式循环按清晰度选;短小逻辑不用复杂抽象,复杂链用中间值说明意图。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-19 | 6. Everyday idioms | RAII guard 绑定到有作用域的变量;let _ = guard_expr 可能立即释放,关键清理必须在正确时间发生。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-20 | 6. Everyday idioms | 使用结构化日志,常量说明单位/来源;命名、导入和拼接建议属于低优先级可读性改进。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-21 | 7. Concurrency and async | 共享状态中相关不变量受同一同步设计保护;缩短锁作用域,核对持锁调用用户回调和返回 guard 的风险。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-22 | 7. Concurrency and async | 公开类型/Future 的 Send/Sync 按运行方式保证;长 CPU 工作离开 executor,库不要无理由强绑运行时。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-23 | 8. Unsafe and FFI | unsafe 限于确有需要的边界,完整论证安全性;不能靠 transmute 延长存活期或 unsafe impl 绕过真实线程约束。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-24 | 8. Unsafe and FFI | FFI 类型/分配器/句柄/回调生命周期清晰;panic 行为与 ABI、panic profile 一致;适用的 unsafe 测试使用 Miri。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-25 | 9. Crates, modules, dependencies | 依赖尽量精简,features 与部署目标匹配;应用锁文件、工作区共享依赖、edition/MSRV 和工具链保持可复现。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-26 | 10. Documentation and comments | 文档解释前置条件、错误、panic、Safety、所有权和副作用;示例可用且避免把 unwrap 当默认错误处理。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-27 | 11. Tests | 测可观察行为、往返、幂等和失败边界;I/O/时间/随机源可控,必要时 fuzz 解析器,不用镜像实现的断言制造覆盖。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-28 | 12. Performance, in order | 先测量再优化;批量操作、缓存/缓冲复用与容量选择基于负载;不可信输入谨慎使用抗碰撞能力弱的 hasher。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/SKILL.md) |
B-29 | rust-review: Write the report | 每项有位置、规则来源、影响及小范围修复;合并同根因重复项,正确性优先于风格,不为了数量凑问题。 | 来源(原始出处:https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-review/SKILL.md) |
继续追溯原始指南
BeautifulRust 对多份指南做了摘要,详细出处仍应随规则保留。下面链接到固定版本的摘要及其原始站点,不将第三方书籍/指南全文重新收录。
- Rust API Guidelines:BeautifulRust 摘要(原始出处:
https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/references/rust-api-guidelines.md);原始指南。 - Google Rust Style Guide:BeautifulRust 摘要(原始出处:
https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/references/google-rust-style-guide.md);原始指南。 - Effective Rust(David Drysdale):BeautifulRust 摘要(原始出处:
https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/references/effective-rust.md);原始指南。 - Rust Design Patterns:BeautifulRust 摘要(原始出处:
https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/references/rust-design-patterns.md);原始指南。 - Microsoft Pragmatic Rust Guidelines:BeautifulRust 摘要(原始出处:
https://github.com/morganlinton/BeautifulRust/blob/b9718436d77ee7bcf17cdcb6aa27628feb95d97a/skills/rust-best-practices/references/microsoft-rust-guidelines.md);原始指南。
IDPS 适配时的差异
- 上游允许对内部不变量使用 expect/panic,甚至建议锁中毒时 expect;IDPS 生产代码禁 unwrap/expect,不能照搬该例外。
- API 命名、bool 参数、是否返回 Vec、是否使用 Arc、是否应用 builder/泛型均按具体成本评估,不自动成为阻断项。
- 不照搬固定 allocator、target-cpu、强制新 lint 或通用 workspace 布局;IDPS 的 Android 目标、多仓结构及 root Makefile 优先。
- 不把“没有 SAFETY 注释”直接等同“已证实 UB”,也不把“手写 Ord 配 derive PartialEq”自动视作错误。