rust

Rust 最佳实践

编写、审查、重构、测试或调试 Rust 代码时，请遵循这些指南。

工作方法

• 首先阅读受影响的代码、测试、Cargo.toml、工具链固定版本和 CI 命令。 遵循项目的 edition、MSRV、功能组合和惯例。
• 如果受影响的 crate 使用 Bevy，请先阅读 Bevy 实践，再将通用的借用、导入或 lint 建议应用于系统函数。
• 应用代码应保持直接：使用具体类型、简单的控制流，不要臆测性地添加 trait 或 builder。需要外部调用者使用的库应谨慎制定公开契约。
• 使用 Rust 的所有权、枚举、trait 和 Result 来建模领域；不要机械地从其他语言照搬继承或异常模式。
• 重构时，除非改动范围包括这些内容，否则应保留公开签名、错误变体、输出顺序和行为。解释必要的契约变更；不要仅为迎合风格偏好而重命名 getter 或替换现有参数。
• 只读审查应给出发现的问题，而不是进行编辑。应将改动限制在请求范围内；本技能不意味着要安装工具、升级依赖或发布。

按任务查阅参考资料

在做出决定前，请阅读相关参考资料。每个主题都有详细规则和示例；只有任务跨越到其他主题时，才遵循交叉链接。

任务	参考资料
借用检查器带来的阻碍、迭代器、导入或函数提取	编码惯用法
Clippy 警告、抑制或工作区 lint 配置	Clippy 与 lint
性能分析、分配、克隆或热点路径	性能
可失败操作、库错误类型或资源清理	错误处理
回归、属性、集成或快照测试；可控 I/O	测试
闭包边界、trait 契约、静态分发或 trait 对象	泛型与分发
编译时状态转换	类型状态
注释、公开文档或可执行示例	文档
生命周期、智能指针、内部可变性或共享所有权	指针与所有权
Tokio 任务、通道、取消或异步共享状态	Tokio 异步
公开类型、构造函数、标准 trait 或 API 演进	API 设计
Unsafe 代码块、原始指针、原生句柄或外部接口	Unsafe 与 FFI
Cargo 清单、依赖、功能、MSRV 或 no_std	Crate 与依赖
声明式/过程宏、生成的 API 或展开诊断	宏
排队操作、可配置算法、AST 遍历或树转换	行为模式
Bevy 系统、查询、调度、延迟变更或 ECS 测试	Bevy

核心规则

• 明确所有权：读取时借用，消费时移动，仅在设计需要多个所有者时共享。添加深拷贝前，先处理好借用作用域。
• 使用类型表达领域不变量，并谨慎设计公开契约。优先采用具体代码；仅在确有需要时引入 trait、构建器、宏或类型状态。
• 对可能失败的操作返回 Result，对正常的缺失情况返回 Option。测试之外绝不使用 unwrap()/expect()。库错误使用 thiserror，二进制程序使用 anyhow；保留错误原因并补充有用的上下文。不要将 panic 或 catch_unwind 用作常规错误处理。保持 Drop 不会触发 panic。
• 在更改所有权、分配、分派或同步方式前，先在 release 构建中测量性能。若循环能更清晰地表达控制流，就保留循环。
• 避免在异步工作线程上执行阻塞 I/O 和繁重的 CPU 运算。在 .await 前结束同步锁的守卫作用域；仅当操作需要时才选择异步同步原语。限制并发，处理取消，并为出站调用设置超时。
• 将不安全代码限制在小范围且健全的边界内，为每个不安全操作记录其不变量，并在每个 unsafe fn 的 # Safety 中记录调用者的义务。
• 保持格式化和 lint 策略与项目及 MSRV 兼容。采用范围小且理由充分的抑制措施；通过 CI 强制将警告视为错误，而不是在源代码中一概使用 #![deny(warnings)]。
• 测试可观察到的行为，包括失败情况和边界条件。修复前先复现 bug；根据各自的契约使用单元测试、集成测试和文档测试。
• 使用 // 说明设计理由，使用 //////! 说明 API 用法和契约。将 TODO 关联到 issue，在适当情况下记录错误、panic 和安全信息，并通过 #![deny(missing_docs)] 强制要求库文档。让可能失败的文档示例可以使用 ? 执行。

交付前验证

使用项目的命令以及受支持的功能/目标矩阵。对于代码更改，运行格式检查、Clippy 和相关测试；对于公开 API/文档更改，还要运行文档测试和 cargo doc --no-deps。根据 MSRV 检查新增语法和依赖。不安全代码、FFI 或性能方面的更改还需要执行适用的 Miri、平台测试或 release 基准测试。报告实际运行的检查及其限制；不要声称未运行的检查已通过。