SuperAPI AI 工具集

idiomatic-rust

编程与开发

查看项目

更新于 11-01 07:16

技能介绍

idiomatic-rust 是一个用于 Rust 代码编写、审查与重构的辅助技能。当出现关于借用、错误处理、分派或测试的 Rust 设计选择,需要符合惯例的答案时,可以调用它。

用途与触发

该技能的触发条件包括:正在编写、审查或重构 Rust 代码,或需要就 Rust 的借用、错误处理、分派、测试等设计问题给出符合惯例的答案。

输入与边界

必需输入为 Rust 任务本身(要编写的代码、待审查的 diff 或设计问题)。当 crate 或工作区根目录不是当前目录时,还需提供该根目录,以获取 Cargo.toml、rust-toolchain.toml 和 edition 固定值。工具链固定版本为可选输入,默认采用流程第一步给出的基线。

该技能的权限为可逆的本地操作:只写入调用任务本来就涉及的 Rust 源文件和项目文件,回滚通过版本控制恢复,不做远程变更。副作用是这些 Rust 源文件可能在调用任务下被修改,章节指引与验证输出会发送到对话中。

使用流程

  1. 确定工具链基线。基线为 Rust 1.98.1 stable(2026-09-03 发布)、edition 2024。Rust 采用六周滚动稳定版本,没有 LTS 通道,因此以当前稳定版为维护目标;若项目固定了更旧的工具链或 edition,则在该固定范围内工作并记录差异。

  2. 将任务路由到手册章节。同一轮中阅读任务涉及的每一章,章节路由表列在参考资料中。

  3. 应用核心约定,包括:

    • 借用与所有权:优先使用 &T 而非 .clone(),除非所有权必须移动;参数用 &str 而非 String、&[T] 而非 Vec<T>;所有权不明确时使用 Cow<'_, T>。
    • Copy 类型:小 Copy 类型按值传递只是启发式而非规则,手册阈值约为两到三个机器字,64 位目标上约 24 字节;实际阈值取决于目标的寄存器和调用约定,热路径应实测。
    • 错误处理:可能失败的操作返回 Result<T, E>;panic! 仅用于不可恢复缺陷;库错误类型用 thiserror,应用二进制用 anyhow;用 ? 传播。生产路径避免 unwrap() 和 expect(),测试与示例可以使用。
    • 性能:用 --release 基准测试;运行 cargo clippy -- -D clippy::perf 获取提示;避免循环内克隆;优先迭代器,避免中间 .collect()。
    • 分派:热路径优先泛型(静态分派);异构集合使用 dyn Trait;在 API 边界装箱,而非内部。
    • 类型状态:必须在编译期拒绝非法转换时,用类型系统编码合法状态。
    • 文档:// 注释写“为什么”(安全性、临时方案、理由);/// 文档注释写公共 API 的“是什么”和“怎么用”;每个 TODO 注明跟踪 issue;库启用 #![deny(missing_docs)]。
  4. 用工具链验证。运行 cargo fmt --check、cargo clippy --all-targets --all-features --locked -- -D warnings 和 cargo test。必须抑制的 lint 使用 #[expect(clippy::lint)] 并附理由注释,不用裸 #[allow]。

参考资料章节

  • chapter_01:借用与克隆、Copy、Option/Result 处理、迭代器、注释、何时提取函数
  • chapter_02:Clippy 配置、关键 lint、工作区 lint 设置
  • chapter_03:性能分析、冗余克隆、栈与堆、零成本抽象
  • chapter_04:Result 与 panic、thiserror 与 anyhow、错误层级
  • chapter_05:测试命名、每个测试一个断言、快照测试
  • chapter_06:静态与动态分派、trait 对象
  • chapter_07:类型状态模式的编译期状态安全
  • chapter_08:何时写注释、文档注释、rustdoc
  • chapter_09:线程安全、Send/Sync、指针类型

失败与恢复

  • 缺少 cargo clippy:用 rustup component add clippy 安装;clippy 是随 rustc 同步发布的 rustup 组件,不是独立版本化包。
  • Clippy 误报:用 #[expect(clippy::lint)] 并附理由注释抑制;lint 不再触发时 expect 会发出警告,因此抑制不会过期。
  • 启发式与实测冲突:以实测为准,启发式只是默认值而非定律。
  • 项目固定旧工具链:在项目固定范围内工作,并报告哪些约定需要更新的工具链。

完成标准

代码或审查符合上述约定,已查阅路由到的章节,工具链验证通过或失败原因已报告。

限制

参考资料中的章节内容继承自固定版本的手册来源,标题所称的 Rust 1.98.1 固定版本并未独立重新验证其逐特性及库层断言。该技能不做远程变更,也不提供超出上述约定的保证。