用途
rust-quality 用于按照 yttrium 项目的既有规范编写惯用、可维护的 Rust 代码,重点覆盖错误处理、类型安全、跨平台兼容和代码组织。它的目标是让新代码与项目现有模式保持一致。
适用与不适用场景
适用场景包括:编写新的 Rust 模块或函数、重构现有 Rust 代码、增加跨平台支持(iOS、Android、WASM)、实现错误类型、创建 newtype 或领域类型、编写测试。
不适用于场景包括:非 Rust 代码库、简单的文档修改、仅有配置变更。
默认工作流
- 先阅读被修改模块或区域的现有代码;
- 遵循既有的导入、类型与错误模式;
- 在实现中加入恰当的 feature gate;
- 在 #[cfg(test)] mod tests 中添加内联测试;
- 运行 just lint 校验格式与 clippy。
主要能力与代码规范
技能给出了项目在多个方面的具体写法示例:
- 导入:使用块状风格并按 crate、外部 crate、std 分组;
- 错误处理:使用 thiserror,并在 uniffi feature 下派生 uniffi_macros::Error;
- newtype:使用完整的派生链,并提供 From、Into 与 Display 实现;
- 结构体 FFI 支持:在 uniffi feature 下派生 uniffi::Record,在 wasm feature 下使用 tsify::Tsify;
- 模块 feature gate:在 lib.rs 中用 #[cfg(feature = "...")] 控制模块是否编译;
- 异步函数:返回 eyre::Result,使用 ? 传播错误;
- 内联测试:在 #[cfg(test)] mod tests 中编写同步与 tokio 异步测试;
- impl 块组织:按构造函数、getter、无副作用准备逻辑、异步操作的顺序排列。
格式与校验要求
- 最大行宽 80 字符;
- 使用 cargo +nightly fmt --all 进行格式化;
- 导入分组粒度设为 imports_granularity = "One";
- 所有 clippy 警告视为错误(-D warnings)。
技能还提供了验证清单,涵盖导入分组、错误派生与描述性消息、FFI 类型的 cfg_attr、newtype 的 From/Into 与 Display、内联测试、无 clippy 警告、行宽限制以及平台相关代码的 feature gate。
应避免的反模式
- 字符串类型化 API(应使用 newtype);
- 在库代码中使用 unwrap()(应使用 ? 配合 eyre::Result);
- 过深的嵌套导入(应扁平化到具体类型);
- 平台代码缺少 feature gate;
- 内联已足够时仍把测试放到单独文件;
- 冗长注释(代码应自解释)。
进阶模式与示例
资料提到 REFERENCE.md 包含自定义 serde 模块(如 duration_millis)、UniFFI 自定义类型映射、平台感知的异步 spawn(原生与 WASM)、带 WASM 支持的异步 trait(?Send)、基于 Arc<RwLock<_>> 的线程安全缓存、serde 枚举模式(tagged unions、rename_all_fields)、Cargo.toml 中的 feature flag 组织以及常量模块模式。
示例部分给出两个完整代码示例:为支付失败新增错误类型,以及创建跨平台的交易请求结构体,并在其中包含内联测试。具体代码可直接参考技能提供的示例。
限制
资料未提供该技能的安装方式、收费情况、支持的平台范围或版本要求,这些信息暂未提供。