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:
@@ -1,16 +1,4 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## 项目概述
|
||||
|
||||
基于 Rust + Axum 的配置驱动型 Mock 服务。在 `mocks/` 目录下通过 YAML 文件定义 API 行为，无需修改代码即可添加/修改接口。
|
||||
|
||||
**核心特性：**
|
||||
- YAML 驱动的请求匹配（method、path、query_params、headers、body）
|
||||
- 热重载：`mocks/*.yaml` 变更自动生效，无需重启服务
|
||||
- 大文件流式响应：通过 `file://` 协议从磁盘流式读取
|
||||
- 文件上传端点：`POST /api/upload`
|
||||
# Mock Server 开发指南
|
||||
|
||||
## 构建与测试命令
|
||||
|
||||
@@ -38,60 +26,31 @@ cargo fmt # 格式化代码
|
||||
```
|
||||
|
||||
**数据流：**
|
||||
|
||||
1. `MockLoader` 扫描 `mocks/` 目录，解析 YAML 为 `MockRule` 结构体
|
||||
2. 规则按路径首段建立索引（如 `/api/users` → key: `api`）存储于 `MockRouter`
|
||||
3. 请求匹配顺序：method → path → query_params → headers → body
|
||||
4. `AppState` 使用 `RwLock` 包装 router，支持线程安全的热重载
|
||||
|
||||
**核心类型 (config.rs)：**
|
||||
## 核心类型 (config.rs)
|
||||
|
||||
- `MockRule`: 完整规则（id, request, response, settings）
|
||||
- `RequestMatcher`: 请求匹配条件（method, path, query_params, headers, body）
|
||||
- `MockResponse`: 响应配置（status, headers, body）
|
||||
- `MockSource`: 枚举类型，支持单接口/多接口 YAML 格式
|
||||
|
||||
**请求匹配 (router.rs)：**
|
||||
## 请求匹配 (router.rs)
|
||||
|
||||
- 路径首段 HashMap 查找，O(1) 获取候选规则
|
||||
- 候选集内线性扫描进行精确匹配
|
||||
- Body 匹配：支持 JSON 对象和字符串两种比较方式
|
||||
|
||||
**响应处理 (handler.rs)：**
|
||||
## 响应处理 (handler.rs)
|
||||
|
||||
- 内联 body：直接返回
|
||||
- `file://` 前缀：从磁盘流式读取文件（低内存占用）
|
||||
- `settings.delay_ms`：模拟网络延迟
|
||||
|
||||
## YAML 配置示例
|
||||
|
||||
**单接口模式：**
|
||||
```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
|
||||
response:
|
||||
body: "file://./data/large-file.pdf"
|
||||
```
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
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:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -15,6 +15,3 @@ logs/
|
||||
|
||||
# 上传文件存储目录
|
||||
storage/
|
||||
|
||||
# Claude Code 配置目录
|
||||
.claude/
|
||||
|
||||
76
README.md
76
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. 安装依赖
|
||||
|
||||
确保已安装 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
|
||||
|
||||
Reference in New Issue
Block a user