SuperAPI AI 工具集

idiomatic-rust

编程与开发

查看项目

更新于 10-28 16:14

技能介绍

用途

该技能针对 Rust 代码的“表达形式”问题:一个熟悉 Rust 的读者期望看到什么样的写法。它管的是代码形态,不涉及所有权模型、错误类型设计或类型驱动设计等决策层面的问题,这些分别由其他技能负责。

主要能力

表达式优先于语句:能返回值的 match 优于在每个分支里给 let mut 赋值;直接产出结果的链式调用优于在循环里设置标志变量、循环后再检查。用类型系统承载不变量,而非运行时检查。let ... else 把提前返回保留在顶部,避免正常路径被嵌套 if let 推向右移;matches! 用于对模式做布尔判断。支持 if-let 链的工具链上可用于组合条件,但需先确认仓库的最低支持 Rust 版本(MSRV)。

迭代器:优先使用迭代器管道,而非索引循环。for i in 0..v.len() { ... v[i] ... } 几乎总有等价的迭代器写法,后者在边界错误时编译失败,而不是运行时 panic。collect 可直接收集为目标类型,包括 HashMap、HashSet、String 和 Result<Vec<_>, _>;最后一种正是 ? 与迭代组合的方式,例如把多行字符串解析为 Vec<i64> 并统一返回 Result。若循环体有真实副作用或提前退出、用组合子会降低清晰度,则普通 for 循环更合适。

类型转换:一个类型可由另一个类型构造时,实现 From;Into 通过 blanket impl 免费获得,因此不要手写两个方向。转换可能失败时实现 TryFrom,而不是用 From 加 panic 或哨兵值。示例:Celsius 到 Fahrenheit 的 From 实现。

优先派生:先用 #[derive(Debug, Clone, PartialEq, Default, Hash)],派生实现基于实际字段生成,结构体变化时自动同步。仅在派生会出错时才手写:Default 需要维护逐字段默认值会破坏的不变量(如百分比总和须为 100 而非各字段为零);Debug 需要隐藏密钥字段(API key、密码);PartialEq 需要忽略不应参与比较的字段(缓存哈希、时间戳)。枚举上用 #[derive(Default)] 加目标变体上的 #[default]。

Newtype:零运行时开销,能把参数顺序写反变成类型错误;当裸 u64、String 或 f64 代表领域概念(ID、货币金额)而非普通数字时应使用。

命名:名字的每个词都要有价值,用 Bookings 而非 BookingService;Service、Manager、Helper、Util、Data、Info 表明命名未完成。as_/to_/into_ 前缀承诺相应成本:零成本视图、分配、消耗。字段访问器不加 get_;缩略词按单词处理(HttpClient、Uuid);不需要 Self 的辅助函数写成自由函数,而不是把 impl 块当命名空间。

重复代码作为设计信号:并非所有重复都能靠派生消除。五个几乎相同的 match 分支,或带十个转发方法的包装器,可能指向缺失的抽象;文档还提示了 Deref 陷阱。

使用方式

按上述规则改写或审查 Rust 代码,用标准三件套验证行为不变、形态改变:cargo clippy --all-targets(仅当仓库没有 lint 配置时才加 -- -D warnings)、cargo fmt --check、cargo test。按仓库配置的 lint 级别运行;除非仓库已启用 clippy::pedantic 组,否则把其发现视为建议而非违规。

适用场景

Rust 代码的编写、重构与评审,尤其是希望代码更符合社区惯用风格、提升可读性与类型安全性的场合。

限制

该技能只约束表达形式,不覆盖 clone 与借用的取舍、错误类型形态、让非法状态不可表示等设计决策。if-let 链等特性受工具链版本限制,需先确认 MSRV。是否采纳 clippy::pedantic 建议取决于仓库配置。