用途:为 rust-engineer 智能体提供 Rust 核心工具链约定,统一代码风格、借用策略、错误处理与异步实践。
版本与工具链:目标为 Rust 2024 edition。MSRV 由约束最强的传递依赖决定,而非 edition 下限,需在 Cargo.toml 中显式固定(rust-version = "...")。每次变更以 cargo fmt --check、cargo clippy -- -D warnings、cargo test 作为门禁;可用时优先用 cargo nextest run 获得更快、隔离的测试执行。
所有权与借用:默认借用,仅在必要时拥有。函数签名接受 &str / &[T] 而非 String / Vec<T>,除非必须取得所有权。返回值应拥有,让调用方借用,避免返回与局部变量绑定的引用。值通常借用偶尔拥有时使用 Cow<'_, str>。仅在真正共享所有权时用 Rc/Arc,优先传引用。内部可变性:单线程用 Cell/RefCell,共享状态并发用 Arc 下的 Mutex/RwLock;绝不在 .await 期间持锁。
错误处理:库代码不使用 unwrap()/expect()/panic!,返回 Result<T, E>。库用 thiserror 定义类型化错误枚举;应用用 anyhow::Result 配合 .context(...) 在边界处补充来源。用 ? 传播,通过 From/#[from] 转换错误。panic! 仅保留给真正不可达的不变量,并说明原因。
异步(tokio):用 #[tokio::main](或显式运行时)与 async/.await 处理 I/O 密集工作。用 tokio::spawn 派生并发任务,用 tokio::join! 或 try_join! 汇合。对所有外部调用用 tokio::time::timeout 设置显式超时。CPU 密集工作交给 tokio::task::spawn_blocking,绝不阻塞运行时。不要在 .await 期间持有 std::sync 锁,改用 tokio::sync 原语。
项目结构与习惯:每个模块单一职责,在 lib.rs 用 pub 暴露精炼的公共 API。按需派生 Debug,以及在廉价且有意义时派生 Clone/PartialEq/Eq。用枚举加穷尽 match 建模状态,避免布尔标志堆砌。优先迭代器链而非手写索引循环。用 newtype(如 struct UserId(u64))让非法状态不可表示。为公共函数写 doctest,兼作可运行文档。
适用场景:Rust 项目的编码规范制定、代码审查与质量门禁、异步服务与库开发。限制:资料未提供具体价格、平台支持范围或性能数据。