# Rust Dev

Rust 开发规范（聚焦 Axum + Tokio 后端栈），覆盖工具链、错误处理、异步陷阱、模块组织、依赖管理与测试规范

- Repository: https://github.com/doccker/cc-use-exp (1063 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-08-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add doccker/cc-use-exp --skill rust-dev -g -a claude-code -y`
Codex: `npx skills add doccker/cc-use-exp --skill rust-dev -g -a codex -y`
Cursor: `npx skills add doccker/cc-use-exp --skill rust-dev -g -a cursor -y`
Gemini CLI: `npx skills add doccker/cc-use-exp --skill rust-dev -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add doccker/cc-use-exp`

## Description

Rust 开发规范（聚焦 Axum + Tokio 后端栈），覆盖工具链、错误处理、异步陷阱、模块组织、依赖管理与测试规范

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Rust 开发规范

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

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

---

## 工具链

```bash
# 格式化
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`）：

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

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

The rest: https://github.com/doccker/cc-use-exp/blob/HEAD/.antigravity/skills/rust-dev/SKILL.md