CNWei
b579a835de
- 将 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>
77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# 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)
|