mock-server/.claude/CLAUDE.md

Mock Server 开发指南

构建与测试命令

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)