SuperAPI AI 工具集

rust-coding-guidelines

编程与开发

查看项目

更新于 11-06 10:04

技能介绍

用途

本技能是一套面向 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 文件为准。