# 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`

## 构建与测试命令

```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`：模拟网络延迟

## 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"
```

## 文件结构

```
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)