rust-dev
Rust 开发规范（聚焦 Axum + Tokio 后端栈），包含错误处理、异步陷阱、模块组织、测试规范等。当操作 .rs、Cargo.toml、Cargo.lock 文件时自动激活。
Informações da origem
- Repositório
- doccker/cc-use-exp
- Última atividade na origem
- 29 de maio de 2026 às 01:33
- Idioma detectado do SKILL.md
- chinês
- Estrelas
- 1.063
- Forks
- 119
Opções de instalação
Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.
Revise os arquivos de origem
Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.
Exibindo SKILL.md
SKILL.md
Instruções da origem · Visualização somente leitura- name
- rust-dev
- description
- Rust 开发规范（聚焦 Axum + Tokio 后端栈），包含错误处理、异步陷阱、模块组织、测试规范等。当操作 .rs、Cargo.toml、Cargo.lock 文件时自动激活。
<instructions>
# Rust 开发规范
> 参考来源: Rust API Guidelines、Rust Async Book、tokio.rs、Axum 官方示例
**适用范围**：后端 Web 服务（Axum + Tokio 路线）。CLI/wasm/嵌入式不在覆盖范围内。
---
## 🛠️ 工具链
```bash
# 格式化
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`。
```rust
#[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 配置：
```toml
[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!` 外部
```rust
// ✅ 阻塞调用包到 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>
Ver no GitHub