用途
本技能是一套面向 Rust 与 GPUI 项目的强制性编码规范,声明在编写任何 Rust 代码之前必须加载,违反规则会导致代码评审失败。它适合作为团队或项目内统一的代码约束清单,用于评审前自查与编码时的规则参照。
核心原则
- 正确性与清晰性优先,速度与效率次之(除非另有说明)。
- 不做未经请求的创造性添加。
- 优先修改已有文件,除非需要新建逻辑组件。
- 注释解释“为什么”而非“做什么”,不写组织性、总结性注释。
错误处理
- 禁止使用
unwrap();应使用?传播,或将Option转换为错误,或显式match处理。 - 禁止静默丢弃错误,例如在可能失败的操作上使用
let _ =;应传播错误、记录错误或显式处理。 - 错误必须传播到 UI,示例展示了在
cx.spawn中匹配结果并更新视图状态与错误字段后调用cx.notify()。
索引安全
直接索引可能越界 panic,应改用 get 并配合 ok_or_else 返回错误。
变量命名
使用完整单词,禁止缩写,例如 queue、count、button。
异步模式
在异步上下文中使用变量遮蔽为克隆值划定作用域,示例展示了 executor.spawn 内先 let task_ran = task_ran.clone(); 再 async move。
文件组织
禁止创建 mod.rs 文件,应使用同名模块文件(如 components.rs 配合 components/ 目录)。对于 crate,应在 Cargo.toml 的 [lib] 中通过 path 指定库根路径。
GPUI 专属规则
- 上下文类型:
App为根上下文;Context<T>在更新Entity<T>时提供并可解引用到App;AsyncApp/AsyncWindowContext来自cx.spawn,可跨 await 点持有。 - 参数顺序:存在
Window时,Window在cx之前。 - Entity 操作:读取用
entity.read(cx);更新时在闭包内使用内部cx调用notify;禁止在更新过程中再次更新同一 entity(会 panic)。 - 测试计时器:GPUI 测试中应使用
cx.background_executor().timer(...)或TestAppContext中的cx.background_executor.timer(...),而不是smol::Timer。 - 事件处理器:使用
cx.listener回调,参数依次为this、事件、window、cx。 - 状态变更后需调用
cx.notify()以触发 UI 更新。 EventEmitter:为视图实现事件类型,并在处理器中通过cx.emit发出事件。- 订阅:将
Subscription存入结构体字段以保持存活,丢弃时自动取消。
项目特定规则
- 项目 Clippy 规则禁止
dbg!()与todo!()宏。 - 所有依赖须在 workspace 的
Cargo.toml中声明,子 crate 使用.workspace = true。
使用方式
技能自身说明要求在编写任何 Rust 代码前加载本规范,并给出提交代码前的快速检查清单:无 unwrap()、可失败操作不使用 let _ =、无 dbg!()/todo!()、变量使用完整名称、不创建 mod.rs、状态变更后调用 cx.notify()、错误传播到 UI、测试中使用 GPUI 计时器、订阅存入结构体字段、entity 更新闭包内使用内部 cx。
适用场景与限制
适用于 Rust 与 GPUI 项目的编码与代码评审。规范中提及的安装命令、收费方式、平台支持等事实暂未提供。规范不保证覆盖所有 Rust 场景,具体项目规则以其 .rule 文件为准。