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>
This commit is contained in:
76
.claude/CLAUDE.md
Normal file
76
.claude/CLAUDE.md
Normal file
@@ -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)
|
||||
89
.claude/rules/commit-spec.md
Normal file
89
.claude/rules/commit-spec.md
Normal file
@@ -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): 简化响应处理逻辑
|
||||
|
||||
将文件响应和内联响应的处理逻辑分离到独立函数中。
|
||||
```
|
||||
89
.claude/rules/mock-spec.md
Normal file
89
.claude/rules/mock-spec.md
Normal file
@@ -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`
|
||||
8
.claude/settings.local.json
Normal file
8
.claude/settings.local.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(find:*)",
|
||||
"Bash(cargo search:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user