@dtt_siye/atool 1.3.0 → 1.4.0

package/skills/project-analyze/rules/rust.md

@@ -1,296 +1,72 @@
 # Rust 项目分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `rust-conventions` skill 作为规范约束。
 
-按 Cargo crate 模块和 `src/` 下的模块层次进行分析。
+## 模块发现策略
 
-```
-main.rs / lib.rs（入口）
-    ↓
-mod 声明（模块组织）
-    ↓
-pub API（公开接口）
-    ↓
-内部模块（实现细节）
-    ↓
-error 模块（错误处理）
-    ↓
-config 模块（配置）
-    ↓
-tests（测试）
-```
+- **Workspace**：检查 `Cargo.toml` 的 `[workspace] members`，每个成员 crate 为独立分析单元
+- **单 Crate**：`src/main.rs`（binary）或 `src/lib.rs`（library），按 `mod` 声明树展开
+- **子模块发现**：`src/*/mod.rs` 或 `src/*.rs` 中的 `pub mod` 声明；每个有 3+ 文件的子目录视为独立模块
+- **跳过**：`target/`、`*.generated.rs`、`tests/`（单独分析）
 
-## 目录扫描策略
+依赖类型检测（从 `Cargo.toml` 判断）：
+- Web API：`actix-web` / `axum` / `warp` / `rocket`
+- CLI：`clap` / `structopt`
+- 异步：`tokio` / `async-std`（检测 `#[tokio::main]`）
 
-### 1. 识别项目结构
+## 入口识别
 
-**信号文件检测：**
-- `Cargo.toml` → Rust 项目
-- `Cargo.lock` → 锁定的依赖版本
-- Workspace: `[workspace] members` in `Cargo.toml`
-- Binary: `src/main.rs`
-- Library: `src/lib.rs`
-- Both: `src/main.rs` + `src/lib.rs`
+| 标记 | 含义 |
+|------|------|
+| `fn main()` / `#[tokio::main] async fn main()` | 应用主入口 |
+| `src/bin/*.rs` | 多二进制入口 |
+| `pub fn` in `src/lib.rs` | 库公开 API 入口 |
+| `.route("path", get/post(...))` (axum) | HTTP 路由入口 |
+| `App::new().service(...)` (actix-web) | HTTP 路由注册 |
+| `#[derive(Parser)] struct Cli` (clap) | CLI 子命令入口 |
 
-### 2. 依赖提取
+## 架构模式识别
 
-从 `Cargo.toml` 提取：
-
-| 类别 | 常见依赖 |
+| 模式 | 检测特征 |
 |------|----------|
-| 异步运行时 | tokio, async-std |
-| Web 框架 | actix-web, axum, warp, rocket |
-| 数据库 | sqlx, diesel, sea-orm |
-| 序列化 | serde, serde_json |
-| 错误处理 | anyhow, thiserror, eyre |
-| CLI | clap, structopt |
-| 日志 | tracing, log, env_logger |
-| HTTP 客户端 | reqwest, hyper |
-| 测试 | proptest, criterion |
-| 加密 | rustls, native-tls |
-
-### 3. 按层扫描路径
+| 分层（Handler/Service/Repo） | `handlers/` + `services/` + `repository/` 目录并存 |
+| Trait 驱动 | 关键接口定义为 `pub trait`，多个 `impl Trait for Struct` |
+| 单模块 | 所有代码在 `main.rs` 或少数顶层 `.rs` 文件，无子目录 |
+| Clean Architecture | `domain/` + `application/` + `infrastructure/` 分离 |
+| 状态机 | 存在 `enum State` + `match state` 的状态转移模式 |
 
-- **入口**: `src/main.rs`, `src/lib.rs`
-- **模块**: `src/` 下的 `mod.rs` 或同名 `.rs` 文件
-- **配置**: `src/config/`, `config/`
-- **错误**: `src/error/`, `src/errors/`
-- **模型**: `src/model/`, `src/models/`
-- **服务**: `src/service/`, `src/handler/`, `src/routes/`
-- **工具**: `src/utils/`, `src/common/`
+## 数据流模式
 
-## 各层提取规则
+- **HTTP 请求链**：Middleware/Layer → Handler → Service → Repository → DB（async）
+- **CLI 执行链**：Cli::parse() → match subcommand → handler fn → output
+- **异步任务链**：`tokio::spawn` → async fn → Channel → Receiver → 处理
+- **错误传播链**：`?` 运算符逐层上抛，最终 `AppError → HTTP 状态码` 映射
 
-### 层 1: 入口分析
+## 分析关注点
 
-**扫描文件**: `src/main.rs`, `src/lib.rs`
+- **所有权图**：识别 `Arc<T>` / `Mutex<T>` / `RwLock<T>` 的共享状态，标注跨线程传递的数据
+- **Trait 边界**：`pub trait` 定义 + 所有 `impl` 实现者，揭示抽象边界和可替换点
+- **错误类型层次**：`thiserror::Error` 枚举的变体 + `From` 转换链 + HTTP 状态码映射
+- **异步边界**：`Send + Sync` 约束是否满足；`async fn` 是否在 `spawn` 中使用
+- **生命周期注解**：`'a` 参数暗示的引用持有关系，识别潜在的借用冲突区域
 
-**提取内容**:
-- `pub mod` 声明（模块组织）
-- `extern crate` 声明
-- `#[macro_use]` 导入
-- `main()` 函数逻辑（应用初始化流程）
+## 输出示例
 
-**输出示例**:
+模块树片段：
 ```
-### 入口文件: src/main.rs
-- **模块声明**:
-  | mod | 路径 | 说明 |
-  |-----|------|------|
-  | config | src/config.rs | 配置管理 |
-  | error | src/error.rs | 错误类型 |
-  | handlers | src/handlers/ | HTTP 处理器 |
-  | models | src/models/ | 数据模型 |
-  | db | src/db.rs | 数据库连接 |
-- **宏导入**: `#[macro_use] extern crate serde`
-- **main() 流程**:
-  加载配置 → 初始化日志 → 连接数据库 → 启动 HTTP 服务 (0.0.0.0:8080)
-```
-
-### 层 2: 公开 API 分析
-
-**扫描文件**: `src/lib.rs`, 各模块的 `pub` 声明
-
-**提取内容**:
-- `pub fn` — 公开函数签名
-- `pub struct` — 公开结构体（字段 + derive 宏）
-- `pub enum` — 公开枚举（变体 + 关联数据）
-- `pub trait` — Trait 定义（方法签名 + 实现者）
-- `impl` 块 — 方法实现
-
-**输出示例**:
-```
-### User struct
-- **路径**: `src/models/user.rs`
-- **定义**:
-  ```rust
-  #[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
-  pub struct User {
-      pub id: i64,
-      pub username: String,
-      pub email: String,
-      pub created_at: chrono::NaiveDateTime,
-  }
-  ```
-- **impl 块方法**:
-  | 方法 | 签名 | 说明 |
-  |------|------|------|
-  | new | (username: &str, email: &str) → Self | 创建用户实例 |
-  | from_row | (row: PgRow) → Result<Self> | 从数据库行转换 |
-
-### UserRepository trait
-- **路径**: `src/repository/user_repository.rs`
-- **方法**:
-  | 方法 | 签名 | 说明 |
-  |------|------|------|
-  | find_by_id | (&self, id: i64) → Result<Option<User>> | 按 ID 查询 |
-  | find_by_email | (&self, email: &str) → Result<Option<User>> | 按邮箱查询 |
-  | create | (&self, user: NewUser) → Result<User> | 创建用户 |
-  | update | (&self, id: i64, user: UpdateUser) → Result<User> | 更新用户 |
-  | delete | (&self, id: i64) → Result<()> | 删除用户 |
-- **实现者**: PgUserRepository
-```
-
-### 层 3: 错误处理分析
-
-**扫描文件**: `src/error.rs`, `src/errors/`
-
-**提取内容**:
-- 自定义 Error 枚举（变体 + 描述）
-- `thiserror` / `anyhow` 使用方式
-- 错误转换链（`From` / `impl Into`）
-
-**输出示例**:
-```
-### AppError
-- **路径**: `src/error.rs`
-- **定义**:
-  ```rust
-  #[derive(Debug, thiserror::Error)]
-  pub enum AppError {
-      #[error("Database error: {0}")]
-      Database(#[from] sqlx::Error),
-      #[error("Not found: {0}")]
-      NotFound(String),
-      #[error("Unauthorized")]
-      Unauthorized,
-      #[error("Validation error: {0}")]
-      Validation(String),
-  }
-  ```
-- **HTTP 映射**: impl IntoResponse for AppError → 400/401/404/500
-```
-
-### 层 4: 异步模式分析
-
-**扫描文件**: 含 `async fn`, `tokio::spawn`, `channel` 的文件
-
-**提取内容**:
-- 异步运行时（tokio / async-std）
-- 并发模式（spawn, join!, select!, channel）
-- 生命周期管理
-
-**输出示例**:
-```
-### 并发模式
-- **运行时**: tokio (multi-threaded)
-- **spawn 任务**:
-  | 任务 | 位置 | 说明 |
-  |------|------|------|
-  | background_sync | main.rs | 定期同步数据 |
-  | notification_sender | handlers/mod.rs | 异步发送通知 |
-- **Channel**:
-  | Channel | 类型 | 生产者 | 消费者 |
-  |---------|------|--------|--------|
-  | event_tx | mpsc::Sender<Event> | handlers | event_processor |
-```
-
-### 层 5: 模块组织分析
-
-**扫描文件**: `src/lib.rs`, `src/*/mod.rs`
-
-**输出示例**:
-```
-### 模块树
 src/
-├── main.rs          # 二进制入口
-├── lib.rs           # 库入口 (pub mod config, error, handlers, models, db)
-├── config.rs        # 配置管理 (env, clap)
-├── error.rs         # 错误类型 (thiserror)
-├── db.rs            # 数据库连接池 (sqlx::PgPool)
-├── handlers/
-│   ├── mod.rs       # Handler 注册
-│   ├── user.rs      # 用户 API
-│   └── auth.rs      # 认证 API
-├── models/
-│   ├── mod.rs
-│   ├── user.rs      # User struct
-│   └── auth.rs      # LoginRequest, Token
-├── repository/
-│   ├── mod.rs
-│   └── user_repository.rs
-└── services/
-    ├── mod.rs
-    └── auth_service.rs
+├── main.rs       — tokio::main，初始化: config → db pool → router → serve
+├── error.rs      — AppError(thiserror): Database/NotFound/Unauthorized/Validation → HTTP 映射
+├── handlers/     — user.rs, auth.rs（axum Router 注册）
+├── models/       — User, NewUser, UpdateUser（Serialize/Deserialize/FromRow）
+└── repository/   — UserRepository trait + PgUserRepository impl
 ```
 
-### 层 6: 测试分析
-
-**扫描文件**: `tests/`, `#[cfg(test)]` 模块
-
-**提取内容**:
-- 单元测试函数列表
-- 集成测试列表
-- 测试工具（mock, fixture）
-
-**输出示例**:
+错误处理片段：
 ```
-### 测试覆盖
-| 文件 | 测试名 | 类型 | 说明 |
-|------|--------|------|------|
-| src/models/user.rs | test_user_creation | 单元测试 | 用户创建验证 |
-| src/handlers/auth.rs | test_login_success | 单元测试 | 登录成功路径 |
-| tests/api_tests.rs | test_create_user | 集成测试 | 完整创建流程 |
-| tests/api_tests.rs | test_get_user_not_found | 集成测试 | 404 处理 |
-```
-
-## 输出模板
-
-### README.md 章节结构
-
-```markdown
-# {项目名}
-
-## 项目概述
-项目功能描述
-
-## 技术栈
-| Crate | 版本 | 用途 |
-|-------|------|------|
-
-## 架构设计
-### 架构图（ASCII）
-### 数据流图
-
-## 模块结构
-模块树 + 各模块职责
-
-## 公开 API
-pub fn / pub struct / pub trait 列表
-
-## 错误处理
-错误类型层次 + HTTP 映射
-
-## 配置
-环境变量 + 配置文件
-
-## 构建 & 运行
-cargo 命令
+AppError variants:
+  Database(#[from] sqlx::Error)  → 500
+  NotFound(String)               → 404
+  Unauthorized                   → 401
+  Validation(String)             → 400
 ```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 二进制入口层 | `src/bin/` | 每个文件 | 文件名去后缀 kebab-case |
-| API/服务层 | `src/` 公开函数按模块 | 每个子目录 | 目录名 kebab-case |
-| 组件层 | `src/` 子目录 | 3+ 文件的子目录 | 目录名 kebab-case |
-| Workspace 成员 | `Cargo.toml` workspace members | 每个成员 crate | crate 名 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `main.rs`, `lib.rs`）
-- 纯导出桶文件（`mod.rs` 仅有 re-export）
-- 工具模块（`util/`, `helper/`）— 合并为一个模块
-- 生成文件（`*.generated.rs`）跳过
-- `target/` 跳过
-
-## Token 管理
-
-- 大模块（>15 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- `Cargo.toml` 依赖分析单独一个子任务
-- `target/` 目录跳过
-- 测试文件（`tests/`, `#[cfg(test)]` 模块）单独分析
-- 生成文件（`*.generated.rs`）跳过