Rust Dev Agent Skill

<instructions>

Rust 开发规范

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

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

🛠️ 工具链

# 格式化
cargo fmt --all
# 静态检查，warning 当 error
cargo clippy --all-targets -- -D warnings
# 测试
cargo test --all-features

版本基线（以 2026-05 为准，半年后重新校准）：edition 2024、Tokio 1.x、Axum 0.8、tower-http 0.6、sqlx 0.8。

命名约定

| 类型 | 规则 | 示例 |

|------|------|------|

| 模块/文件 | snake_case | user_service.rs |

| 函数/变量 | snake_case | fetch_user, db_pool |

| 类型/Trait/Enum | UpperCamelCase | UserRepo, AppError |

| 常量/静态 | SCREAMING_SNAKE_CASE | MAX_RETRY |

禁止: common、util、helper、base 等无意义模块名。

错误处理

分场景选边：库用 thiserror，二进制应用用 anyhow，跨边界（handler）用自定义 AppError + IntoResponse。

#[derive(thiserror::Error, Debug)]
pub enum AppError {
    #[error("db error: {0}")]
    Db(#[from] sqlx::Error),
    #[error("not found")]
    NotFound,
    #[error("bad request: {0}")]
    BadRequest(String),
}

禁止生产代码：.unwrap() / .expect() / panic!()（仅测试可用）。clippy 配置：

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

异步编程红线

• 阻塞调用必须 spawn_blocking：CPU > 10ms、std::fs、同步 DB driver 都不能直接进 async fn
• 不要跨 .await 持有 std::sync::Mutex：用 tokio::sync::Mutex
• Rc/RefCell 不能跨 .await：违反 Send 边界，改 Arc / 缩小作用域
• tokio::select! 分支必须取消安全：不确定时把状态保存到 select! 外部

// ✅ 阻塞调用包到 spawn_blocking
let data = tokio::task::spawn_blocking(|| std::fs::read("big.bin")).await??;

Axum 实战要点

• State 一律 Arc 包装，不要克隆裸结构体
• Handler 错误类型实现 IntoResponse，统一对外 status + json
• 路由按模块拆 fn routes() -> Router<AppState> + Router::nest
• 超时/限流/日志/CORS 走 tower-http 中间件

性能优化建议

| 场景 | 解决方案 |

|------|---------|

| 循环内字符串拼接 | String::with_capacity + push_str |

| Vec 频繁扩容 | Vec::with_capacity(n) |

| 循环内 .clone() 大对象 | 借用或 Arc<T> |

| Box<dyn Trait> 滥用 | 优先泛型 <T: Trait> 静态分发 |

| 阻塞 IO 在 async 里 | tokio::task::spawn_blocking |

unsafe 红线

业务代码原则禁用 unsafe。必须用时（FFI / 极端性能）：

• 块前必须有 // SAFETY: ... 注释，说明保持的不变量
• 缩小 unsafe 块到最小范围，封装成 safe API 对外暴露

> 📋 本回复遵循：rust-dev - [章节]

</instructions>