docs: 重构项目文档结构

- 将 CLAUDE.md 移至 .claude/ 目录，精简为 AI 开发指南 - 扩充 README.md 为完整的用户文档 - 新增 rules/mock-spec.md: YAML 配置生成规范 - 新增 rules/commit-spec.md: Git 提交消息格式规范 - 从 .gitignore 移除 .claude/ 目录以便跟踪 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
feat: 优化CLAUDE.md
2026-03-24 18:44:06 +08:00 · 2026-03-22 21:46:22 +08:00
7 changed files with 334 additions and 237 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,76 @@
+# Mock Server 开发指南
+
+## 构建与测试命令
+
+```bash
+cargo build              # 构建项目
+cargo run                # 启动服务 http://127.0.0.1:8080
+cargo test               # 运行所有测试
+cargo test <pattern>     # 运行匹配的测试（如 `cargo test router`）
+cargo clippy             # 代码检查
+cargo fmt                # 格式化代码
+```
+
+## 架构
+
+```
+┌─────────────┐    ┌──────────────┐    ┌────────────────┐
+│  loader.rs  │───▶│   router.rs  │───▶│   handler.rs   │
+│ YAML → 索引 │    │ HashMap 索引  │    │  请求/响应处理  │
+└─────────────┘    └──────────────┘    └────────────────┘
+       ▲                                       │
+       │         ┌──────────────────┐          │
+       └─────────│   main.rs        │◀─────────┘
+         热重载   │ AppState(RwLock)│
+                 └──────────────────┘
+```
+
+**数据流：**
+
+1. `MockLoader` 扫描 `mocks/` 目录，解析 YAML 为 `MockRule` 结构体
+2. 规则按路径首段建立索引（如 `/api/users` → key: `api`）存储于 `MockRouter`
+3. 请求匹配顺序：method → path → query_params → headers → body
+4. `AppState` 使用 `RwLock` 包装 router，支持线程安全的热重载
+
+## 核心类型 (config.rs)
+
+- `MockRule`: 完整规则（id, request, response, settings）
+- `RequestMatcher`: 请求匹配条件（method, path, query_params, headers, body）
+- `MockResponse`: 响应配置（status, headers, body）
+- `MockSource`: 枚举类型，支持单接口/多接口 YAML 格式
+
+## 请求匹配 (router.rs)
+
+- 路径首段 HashMap 查找，O(1) 获取候选规则
+- 候选集内线性扫描进行精确匹配
+- Body 匹配：支持 JSON 对象和字符串两种比较方式
+
+## 响应处理 (handler.rs)
+
+- 内联 body：直接返回
+- `file://` 前缀：从磁盘流式读取文件（低内存占用）
+- `settings.delay_ms`：模拟网络延迟
+
+## 文件结构
+
+```
+src/
+├── main.rs      # 入口，热重载监听，Axum 路由配置
+├── config.rs    # 数据结构定义（MockRule, RequestMatcher 等）
+├── loader.rs    # YAML 解析，目录扫描
+├── router.rs    # 路径首段索引，匹配逻辑
+├── handler.rs   # 统一请求处理器，文件流式响应
+└── upload.rs    # Multipart 文件上传处理
+
+tests/           # 集成测试（每个模块一个测试文件）
+mocks/           # YAML Mock 配置文件
+storage/         # 上传文件存储（按 YYYY-MM-DD 分目录）
+```
+
+## 开发注意事项
+
+- **Rust Edition 2024**，Axum 0.8.8
+- 测试使用 `tempfile` crate 处理临时文件
+- 请求体大小限制：10MB (handler.rs:30)
+- 热重载防抖时间：200ms (main.rs:46)
+- Header 匹配大小写不敏感 (router.rs:75)
--- a/.claude/rules/commit-spec.md
+++ b/.claude/rules/commit-spec.md
@@ -0,0 +1,89 @@
+---
+paths:
+  - "**/*"
+---
+
+## Git 提交消息规范
+
+AI 在生成 commit 消息时必须遵循以下格式。
+
+### 格式
+
+```
+<类型>(<范围>): <描述>
+
+[可选的详细说明]
+
+[可选的脚注]
+```
+
+### 类型（Type）
+
+| 类型 | 说明 |
+|------|------|
+| feat | 新功能（feature） |
+| fix | 修复 bug |
+| docs | 文档更新 |
+| style | 代码格式（不影响功能的变动） |
+| refactor | 代码重构（既非新功能也非 bug 修复） |
+| test | 添加或修改测试 |
+| chore | 构建系统或辅助工具的变动 |
+| perf | 性能优化 |
+
+### 范围（Scope）
+
+描述提交影响的功能模块或组件（可选）。
+
+### 描述（Description）
+
+- 简明扼要描述变动内容
+- 首字母小写
+- 不超过 100 个字符
+- 使用祈使句（如 "add" 而非 "added"）
+
+### 详细说明（Body）
+
+- 提供更多上下文和详细说明（可选）
+- 每行不超过 72 个字符
+- 说明"做了什么"和"为什么"
+
+### 脚注（Footer）
+
+- 破坏性变动说明（如 `BREAKING CHANGE: ...`）
+- 关闭的 Issue（如 `Closes #123`）
+
+### 示例
+
+**新功能：**
+
+```
+feat(api): 添加用户登录端点
+
+- 实现 JWT 认证逻辑
+- 添加登录表单前端组件
+- 更新用户服务处理登录请求
+
+Closes #45
+```
+
+**Bug 修复：**
+
+```
+fix(router): 修复路径匹配大小写问题
+
+路径匹配在某些情况下区分大小写导致无法正确路由到处理器。
+```
+
+**文档更新：**
+
+```
+docs: 更新 README 中的安装说明
+```
+
+**重构：**
+
+```
+refactor(handler): 简化响应处理逻辑
+
+将文件响应和内联响应的处理逻辑分离到独立函数中。
+```
--- a/.claude/rules/mock-spec.md
+++ b/.claude/rules/mock-spec.md
@@ -0,0 +1,89 @@
+---
+paths:
+  - "mocks/**/*.{yml,yaml}"
+---
+
+## YAML 配置规范
+
+AI 在生成 Mock 规则时必须遵循以下格式。
+
+### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| id | string | 是 | 规则唯一标识 |
+| request.method | string | 是 | HTTP 方法 (GET/POST/PUT/DELETE...) |
+| request.path | string | 是 | 请求路径，精确匹配 |
+| request.query_params | object | 否 | 查询参数匹配 |
+| request.headers | object | 否 | 请求头匹配（大小写不敏感） |
+| request.body | any | 否 | 请求体匹配，支持 JSON 对象或字符串 |
+| response.status | number | 是 | HTTP 状态码 |
+| response.headers | object | 否 | 响应头 |
+| response.body | string | 是 | 响应体，支持 file:// 前缀 |
+| settings.delay_ms | number | 否 | 延迟响应（毫秒） |
+
+### 匹配规则
+
+1. **路径精确匹配**（非前缀匹配）
+2. **请求头匹配大小写不敏感**
+3. **Body 匹配**支持 JSON 对象或字符串比较
+
+### 配置示例
+
+**单接口模式：**
+
+```yaml
+id: "login"
+request:
+  method: "POST"
+  path: "/api/login"
+  body: { "username": "test" }
+response:
+  status: 200
+  body: '{"token": "xxx"}'
+settings:
+  delay_ms: 100
+```
+
+**多接口模式（数组）：**
+
+```yaml
+- id: "get-users"
+  request: { method: "GET", path: "/api/users" }
+  response: { status: 200, body: '{"users": []}' }
+
+- id: "create-user"
+  request: { method: "POST", path: "/api/users" }
+  response: { status: 201, body: '{"id": 1}' }
+```
+
+**带查询参数和请求头：**
+
+```yaml
+id: "search-users"
+request:
+  method: "GET"
+  path: "/api/users"
+  query_params: { "role": "admin" }
+  headers: { "Authorization": "Bearer token" }
+response:
+  status: 200
+  headers: { "X-Total-Count": "100" }
+  body: '{"users": []}'
+```
+
+**文件响应：**
+
+```yaml
+id: "download-pdf"
+request:
+  method: "GET"
+  path: "/api/download"
+response:
+  status: 200
+  body: "file://./data/large-file.pdf"
+```
+
+> `file://` 支持两种路径：
+> - 相对路径：`file://./data/file.pdf`（相对于项目根目录）
+> - 绝对路径：`file:///C:/path/to/file.pdf`
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(cargo search:*)"
+    ]
+  }
+}
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,3 @@ logs/

 # 上传文件存储目录
 storage/
-
-# Claude Code 配置目录
-.claude/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,228 +0,0 @@
-# Mock Server 项目指南
-
-## 项目概述
-
-基于 Rust + Axum 的配置驱动型 Mock 服务，支持 YAML 配置、请求匹配、延迟响应、大文件流式返回和文件上传等特性。
-
-## 技术栈
-
- **语言**: Rust (Edition 2024)
- **Web 框架**: Axum 0.8.8 + axum-extra (multipart 支持)
- **异步运行时**: Tokio
- **序列化**: serde + serde_yaml + serde_json
- **工具库**: walkdir, uuid, chrono, tokio-util
-
-## 项目结构
-
-```
-mock-server/
-├── src/
-│   ├── main.rs        # 程序入口，路由配置，服务启动
-│   ├── lib.rs         # 库模块导出
-│   ├── config.rs      # 配置结构定义 (MockRule, MockResponse, MockSettings)
-│   ├── loader.rs      # YAML 配置加载器，递归扫描 mocks 目录
-│   ├── router.rs      # 路由匹配引擎，基于路径首段索引
-│   ├── handler.rs     # 请求处理器，统一处理所有 Mock 请求
-│   └── upload.rs      # 文件上传处理模块
-├── tests/             # 集成测试
-│   ├── config_test.rs      # 配置模块测试
-│   ├── handler_test.rs     # 请求处理测试
-│   ├── integration_test.rs # 集成测试
-│   ├── loader_test.rs      # 加载器测试
-│   ├── router_test.rs      # 路由匹配测试
-│   └── upload_test.rs      # 文件上传测试
-├── mocks/             # YAML Mock 配置文件目录
-├── storage/           # 上传文件存储目录 (按日期分类: YYYY-MM-DD)
-└── Cargo.toml
-```
-
-## 核心模块说明
-
-### config.rs - 配置结构
-
-定义 Mock 规则的数据结构：
- `MockRule`: 完整的 Mock 规则（id, request, response, settings）
- `MockRequest`: 请求匹配条件（method, path, query_params, headers, body）
- `MockResponse`: 响应配置（status, headers, body）
- `MockSettings`: 额外设置（delay_ms 延迟）
- `MockSource`: 支持单接口和多接口 YAML 格式
-
-**文件协议**: body 以 `file://` 开头时，从磁盘流式读取文件
-
-### loader.rs - 配置加载器
-
- `MockLoader::load_all_from_dir()`: 递归扫描目录下的 .yaml/.yml 文件
- 按路径首段建立索引（如 `/api/users` -> key: `api`）
- 支持单接口和多接口两种 YAML 格式
-
-### router.rs - 路由匹配引擎
-
- 基于路径首段的 HashMap 快速索引
- 线性深度匹配：method -> path -> query_params -> headers -> body
- 支持大小写不敏感的方法匹配
- 支持尾部斜杠忽略
-
-### handler.rs - 请求处理器
-
- 统一处理所有 HTTP 方法和路径
- 支持延迟响应（settings.delay_ms）
- 支持文件流式响应（低内存占用）
- 匹配失败返回 404
-
-### upload.rs - 文件上传
-
- 路由: `POST /api/upload`
- 支持 multipart/form-data 格式
- 文件存储: `storage/YYYY-MM-DD/uuid.extension`
- 返回 JSON 格式的文件信息
-
-## 常用命令
-
-```bash
-# 构建项目
-cargo build
-
-# 运行项目
-cargo run
-
-# 运行所有测试
-cargo test
-
-# 运行特定测试
-cargo test test_name
-
-# 检查代码
-cargo check
-
-# 格式化代码
-cargo fmt
-
-# 代码检查
-cargo clippy
-```
-
-## YAML 配置示例
-
-### 单接口模式
-
-```yaml
-id: "user-login"
-request:
-  method: "POST"
-  path: "/api/v1/login"
-  query_params:
-    redirect: "/dashboard"
-  headers:
-    Content-Type: "application/json"
-  body:
-    username: "test"
-    password: "123456"
-response:
-  status: 200
-  headers:
-    Content-Type: "application/json"
-  body: '{"code": 0, "message": "success", "data": {"token": "xxx"}}'
-settings:
-  delay_ms: 100
-```
-
-### 多接口模式
-
-```yaml
- id: "get-users"
-  request:
-    method: "GET"
-    path: "/api/users"
-  response:
-    status: 200
-    body: '{"users": []}'
-
- id: "create-user"
-  request:
-    method: "POST"
-    path: "/api/users"
-  response:
-    status: 201
-    body: '{"id": 1}'
-```
-
-### 文件响应模式
-
-```yaml
-id: "download-file"
-request:
-  method: "GET"
-  path: "/api/download"
-response:
-  status: 200
-  headers:
-    Content-Type: "application/pdf"
-  body: "file://./data/document.pdf"
-```
-
-## 开发规范
-
-### 代码风格
-
- 使用 Rust 标准命名约定：snake_case for functions/variables, PascalCase for types
- 公开函数添加文档注释 `///`
- 错误处理使用 `Result` 和 `Option`
- 异步函数使用 `async/await`
-
-### 测试规范
-
- 每个模块对应一个测试文件
- 测试函数命名：`test_<模块>_<场景>`
- 使用 `tempfile` crate 处理临时文件
- 测试应该独立运行，不依赖执行顺序
-
-### Git 提交规范
-
-```
-feat: 新功能
-fix: 修复 bug
-docs: 文档更新
-test: 测试相关
-refactor: 代码重构
-chore: 构建/工具变更
-```
-
-## API 端点
-
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/api/upload` | POST | 文件上传 |
-| `/*` | ANY | Mock 请求处理（由 YAML 配置定义） |
-
-## 文件上传响应格式
-
-```json
-{
-  "success": true,
-  "files": [
-    {
-      "original_name": "document.pdf",
-      "stored_name": "550e8400-e29b-41d4-a716-446655440000.pdf",
-      "path": "storage/2026-03-19/550e8400-e29b-41d4-a716-446655440000.pdf",
-      "size": 1024,
-      "content_type": "application/pdf"
-    }
-  ],
-  "message": "Files uploaded successfully"
-}
-```
-
-## 扩展功能规划
-
- [ ] 热加载：配置文件变更自动重载
- [ ] 动态占位符：支持 `{{timestamp}}`, `{{uuid}}` 等
- [ ] 管理界面：Web UI 管理 Mock 规则
- [ ] 请求录制：自动生成 Mock 配置
- [ ] 条件匹配：基于请求体的复杂匹配规则
-
-## 注意事项
-
-1. **文件协议**: 使用 `file://` 时确保文件路径正确
-2. **延迟响应**: 仅用于测试，生产环境请移除
-3. **上传目录**: 确保 `storage/` 目录有写入权限
-4. **内存限制**: 请求体限制为 10MB
--- a/README.md
+++ b/README.md
@@ -1,11 +1,77 @@
 # mock-server
-基于Rust/Axum的配置驱动型Mock服务，支持YAML配置、请求匹配、延迟响应、大文件流式返回等特性。
+
+基于 Rust/Axum 的配置驱动型 Mock 服务，支持 YAML 配置、请求匹配、热重载、延迟响应、大文件流式返回等特性。

 ## 特性
- 配置驱动：YAML定义API行为，无需修改代码
- 高性能：基于Rust异步运行时，哈希索引匹配请求
- 低内存：大响应体支持磁盘文件流式读取，不占用常驻内存
- 易扩展：模块化设计，支持动态占位符、热加载（规划中）
+
+- **配置驱动**：YAML 定义 API 行为，无需修改代码
+- **热重载**：`mocks/*.yaml` 变更自动生效，无需重启服务
+- **高性能**：基于 Rust 异步运行时，路径首段哈希索引 O(1) 匹配
+- **低内存**：大响应体支持 `file://` 协议从磁盘流式读取
+- **文件上传**：内置 `/api/upload` 端点，按日期分目录存储

 ## 快速开始
-### 1. 安装依赖
+
+### 1. 安装依赖
+
+确保已安装 Rust 工具链：
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+### 2. 构建与运行
+
+```bash
+cargo build              # 构建项目
+cargo run                # 启动服务 http://127.0.0.1:8080
+cargo test               # 运行所有测试
+cargo test <pattern>     # 运行匹配的测试（如 cargo test router）
+cargo clippy             # 代码检查
+cargo fmt                # 格式化代码
+```
+
+## 文件结构
+
+```
+src/
+├── main.rs      # 入口，热重载监听，Axum 路由配置
+├── config.rs    # 数据结构定义（MockRule, RequestMatcher 等）
+├── loader.rs    # YAML 解析，目录扫描
+├── router.rs    # 路径首段索引，匹配逻辑
+├── handler.rs   # 统一请求处理器，文件流式响应
+└── upload.rs    # Multipart 文件上传处理
+
+tests/           # 集成测试（每个模块一个测试文件）
+mocks/           # YAML Mock 配置文件
+storage/         # 上传文件存储（按 YYYY-MM-DD 分目录）
+```
+
+## Mock 配置
+
+详细配置规范请参考 [.claude/rules/mock-spec.md](.claude/rules/mock-spec.md)
+
+## API
+
+### 文件上传
+
+```http
+POST /api/upload
+Content-Type: multipart/form-data
+
+file: <binary>
+```
+
+**响应示例：**
+
+```json
+{
+  "filename": "example.txt",
+  "path": "storage/2024-01-15/example.txt",
+  "size": 1024
+}
+```
+
+## 许可证
+
+MIT