用途:为资深到首席级 Rust 工程师提供工程实践手册,目标是让代码在生产压力下保持正确、可观测、可维护。
主要能力:涵盖架构与边界划分、所有权与借用、异步与并发、错误处理、可观测性、安全、测试与生产就绪。默认标准包括:main.rs 保持精简,业务逻辑放入可测试模块或 crate;领域错误用 thiserror,应用边界与 CLI 用 anyhow;生产路径禁止 unwrap()/expect();trait 在消费方边界引入;优先用所有权与借用使非法状态不可表示,再考虑 Arc<Mutex<_>>;每个 spawn 任务需有归属、取消路径与错误处理策略;unsafe 代码隔离、最小化并说明不变量。文档给出错误传播、任务取消与错误上报的对比示例。
工作流:复现或以失败测试固化行为;划分边界(transport、编排、领域、适配器、持久化);定义失败模式(panic、取消、部分写入、重试、超时、关闭);实现最小端到端切片;按风险补充测试、基准或属性测试;校验格式、lint、安全与发布行为。
验证命令保持原样:cargo fmt --all --check;cargo clippy --workspace --all-targets --all-features -- -D warnings;cargo test --workspace --all-features;cargo test -- --nocapture;cargo nextest run --workspace --all-features(若可用);cargo llvm-cov(需覆盖率时);cargo audit(发布前);cargo deny check(仓库使用许可证/公告策略检查时)。
架构与并发护栏:优先模块化单体而非拆分多 crate/服务;方向为 transport -> use-case -> domain -> ports -> adapters;边界处统一映射错误;避免共享可变状态优先;使用 Arc<Mutex<_>> 需文档化不变量与预期争用;限制 fan-out 并发;出站 IO 与数据库获取须设超时;将取消视为正确性的一部分。
服务/API 与安全:结构化 tracing 带稳定字段(service、trace_id、request_id、tenant_id、status);暴露健康/就绪端点;边界校验输入;明确错误分类(invalid、unauthorized、forbidden、not-found、conflict、unavailable);副作用操作尽量幂等。安全清单:日志、panic 信息与 Debug 输出不得含密钥;校验不可信输入的长度、数量、递归深度与体积;参数化 SQL 与最小权限凭据;高风险系统出站网络与文件操作使用允许列表;unsafe 块按安全敏感代码隔离并评审。
性能:用 criterion、火焰图或 profiler 先测量再优化,关注 clone 频率、分配抖动、锁争用与序列化热点;仅在真实瓶颈且保持可读性时使用零拷贝与借用;panic = "abort" 需理解运维权衡后使用。
参考资料包含 references/ 下架构、高级模式、缺陷预防、代码评审、调试与性能分析、数据库与 SQLX、HTTP 服务模式、可观测性、可靠性、资深习惯、可信库、生产就绪等文档;脚本 scripts/scaffold_project.py 用于搭建项目骨架,assets/github-ci.yml 为 GitHub Actions CI 基线。限制:文档未说明具体版本号、支持的平台、性能数据与定价等信息,暂未提供。