SuperAPI AI 工具集

rust-best-practices

编程与开发

查看项目

更新于 10-15 20:32

技能介绍

用途:在审查或重构 Rust 代码时,按最佳实践清单提升质量与惯用法。语言基础请用 rust 技能,Axum 相关请用 axum / rust-axum-production。

持续检查清单(每个 PR/改动范围):cargo fmt;cargo clippy --all-targets -- -D warnings(或 CI 标准);cargo test;不新增无跟踪的 TODO/unwrap;新代码把警告当错误。

惯用法:parse, don't validate,尽早把输入转为有效类型;优先清晰的迭代器与组合子而非手写索引;match 穷尽,if let 仅用于单一相关分支;避免遗留 ref,使用现代解构;用 Default、builder 或带明确前置条件的 new;命名遵循 snake_case、类型 UpperCamelCase、常量 SCREAMING_SNAKE;对外 API 的 pub 项用 /// 文档并附示例。

API 设计(crate/库):最小化 pub 表面;semver 下谨慎处理破坏性变更,可选功能用 Cargo features;仅在真正提升易用性时接受 impl AsRef<Path> / impl Into<String>;返回具体类型或稳定的 impl Trait,公共库尽量不用 Box<dyn Error>;不必要不暴露内部依赖类型;可能增长的公共 enum/struct 加 #[non_exhaustive]。

所有权:需要保存数据时接受 impl Into<T> 或明确所有权,不用 &String;优先 &str 而非 &String、&[T] 而非 &Vec<T>;内部可变性(Cell/RefCell/Mutex)须有理由并记录线程安全(Send/Sync);热路径避免 clone,先测量再微优化。

错误与 panic:库用 thiserror 与枚举错误;应用边界用 anyhow/eyre(若已采用);内部不变量用带说明的 expect;外部输入返回 Result,绝不 panic;链式添加上下文,不丢弃 source;敏感区域可启用 clippy::unwrap_used / expect_used。

unsafe:最后手段,每个 unsafe 块注释安全不变量,封装为最小安全 API;不照搬 Stack Overflow 的 unsafe;优先使用经审计的 crate(bytes、zerocopy 等)。

并发:用 Arc 共享,Mutex/RwLock 或 channel 修改;消息传递减少争用;async 中不用 std::thread::sleep,改用 tokio::time;注意锁顺序防死锁;Send/Sync 错误应修设计而非乱加包装。

依赖:少而知名且维护良好;仓库已用则跑 cargo deny / cargo audit,否则审计关键升级;feature flags 只开所需;避免语义重复的 crate。

测试与质量:单元+集成测试,解析器/不变量用 proptest 属性测试;快照测试仅在团队已用且会审查时;criterion 基准只针对真实回归;CI 跑 fmt + clippy + test(+ 声明的 MSRV)。

应消除的坏味道:把 String 当万能类型;该用新绑定时却用 mut 与重新赋值;utils 大杂烩模块;叙述显而易见之事的注释;无理由的大范围 #[allow(clippy::...)];以防万一而注释掉的代码。

完成标准:范围内 Clippy 干净(或局部有理由的 allow);API/pub 最小且对外有文档;错误惯用,panic 仅用于不变量;无 unsafe 或已封装并注明不变量;测试覆盖重构回归。