Rust 开发规范

参考来源：Rust API Guidelines、Rust Async Book、tokio.rs、Axum 官方示例、Effective Rust

适用范围：后端 Web 服务（Axum + Tokio 路线）。CLI/wasm/嵌入式不在本规范覆盖范围内。

---

工具链

# 格式化
cargo fmt --all
# 静态检查，warning 当 error
cargo clippy --all-targets -- -D warnings
# 测试
cargo test --all-features
# CVE 扫描（独立安装）
cargo audit
# 许可证/重复依赖检查（独立安装）
cargo deny check
# 检测未使用依赖
cargo machete

edition：新项目默认 edition = "2024"，老项目保持 2021 不强迁。

版本基线（写死，避免重复决策）：

• Tokio 1.x，Axum 0.8，tower-http 0.6
• serde 1、tracing 0.1、tracing-subscriber 0.3
• DB：sqlx 0.8（runtime-tokio-rustls）

---

命名约定

类型	规则	示例
模块/文件	snake_case	user_service.rs
函数/变量	snake_case	fetch_user, db_pool
类型/Trait/Enum	UpperCamelCase	UserRepo, AppError
常量/静态	SCREAMING_SNAKE_CASE	MAX_RETRY
泛型	单大写或 UpperCamelCase	T, Req, Resp
生命周期	短小写	'a, 'ctx

禁止：common、util、helper、base 等无意义模块名。模块按职责命名（api、db、service）。

---

模块组织

参照 apple-store-price-rs / org-site-backend 的实证拆分，按职责切文件，不堆 lib.rs：

src/
├── main.rs          # 仅 bootstrap：日志初始化、读配置、建路由、启服务
├── config.rs        # 配置加载（env / toml）
├── error.rs         # AppError + IntoResponse impl
├── db.rs            # 数据库连接池/迁移
├── api.rs           # 路由聚合 + handler
├── service/         # 业务逻辑（无副作用层）
│   └── user.rs
└── models.rs        # 领域类型 + serde 派生

可见性：pub(crate) 优先于 pub。只在确实要对外暴露时才用 pub。

---

错误处理（核心）

分场景选边：

场景	选择	理由
库 crate	thiserror	调用方需要按变体匹配
二进制应用顶层	anyhow	只关心"成功/失败 + 上下文"
跨边界（handler / 公共 API）	自定义 AppError + IntoResponse	控制对外错误形态

禁止生产代码出现：

• .unwrap() / .expect()（仅测试和 const 上下文可用）
• panic!()（仅用于"逻辑上不可达"且带 SAFETY 注释）

clippy 配置（在 Cargo.toml 或 clippy.toml）：

[lints.clippy]
unwrap_used = "deny"
expect_used = "deny"
panic = "deny"

错误传播用 ?，跨类型用 From 实现自动转换：