feat: 实现核心匹配引擎与请求处理器并修复解析逻辑

- 新增 router 模块：实现基于路径首段索引子集匹配。 - 新增 handler 模块：集成 Axum 处理器，支持 Smart Body 协议与延迟模拟。 - 修复解析与匹配故障：修正 YAML 字段类型解析错误。
feat: 实现配置加载系统与多级目录递归扫描
2025-12-26 15:21:03 +08:00 · 2025-12-25 18:01:09 +08:00
14 changed files with 883 additions and 7 deletions
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -84,6 +84,22 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"

+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -145,6 +161,18 @@ dependencies = [
 "slab",
 ]

+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
@@ -249,12 +277,24 @@ version = "1.0.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7ee5b5339afb4c41626dde77b7a611bd4f2c202b897852b4bcf5d03eddc61010"

+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
 [[package]]
 name = "libc"
 version = "0.2.178"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37c93d8daa9d8a012fd8ab92f088405fb202ea0b6ab73ee2482ae66af4f42091"

+[[package]]
+name = "linux-raw-sys"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -300,7 +340,7 @@ dependencies = [
 ]

 [[package]]
-name = "mock-server"
+name = "mock_server"
 version = "0.1.0"
 dependencies = [
 "axum",
@@ -308,8 +348,21 @@ dependencies = [
 "serde",
 "serde_json",
 "serde_yaml",
+ "tempfile",
 "tokio",
 "tokio-util",
+ "tracing",
+ "tracing-subscriber",
+ "walkdir",
+]
+
+[[package]]
+name = "nu-ansi-term"
+version = "0.50.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
+dependencies = [
+ "windows-sys 0.61.2",
 ]

 [[package]]
@@ -377,6 +430,12 @@ dependencies = [
 "proc-macro2",
 ]

+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -386,12 +445,34 @@ dependencies = [
 "bitflags",
 ]

+[[package]]
+name = "rustix"
+version = "1.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "146c9e247ccc180c1f61615433868c99f3de3ae256a30a43b49f67c2d9171f34"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "ryu"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "62049b2877bf12821e8f9ad256ee38fdc31db7387ec2d3b3f403024de2034aea"

+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
@@ -477,6 +558,15 @@ dependencies = [
 "unsafe-libyaml",
 ]

+[[package]]
+name = "sharded-slab"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+dependencies = [
+ "lazy_static",
+]
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.7"
@@ -525,6 +615,28 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"

+[[package]]
+name = "tempfile"
+version = "3.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "655da9c7eb6305c55742045d5a8d2037996d61d8de95806335c7c86ce0f82e9c"
+dependencies = [
+ "fastrand",
+ "getrandom",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "thread_local"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "tokio"
 version = "1.48.0"
@@ -602,9 +714,21 @@ checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
 "log",
 "pin-project-lite",
+ "tracing-attributes",
 "tracing-core",
 ]

+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "tracing-core"
 version = "0.1.36"
@@ -612,6 +736,32 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
 "once_cell",
+ "valuable",
+]
+
+[[package]]
+name = "tracing-log"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
+dependencies = [
+ "log",
+ "once_cell",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-subscriber"
+version = "0.3.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f30143827ddab0d256fd843b7a66d164e9f271cfa0dde49142c5ca0ca291f1e"
+dependencies = [
+ "nu-ansi-term",
+ "sharded-slab",
+ "smallvec",
+ "thread_local",
+ "tracing-core",
+ "tracing-log",
 ]

 [[package]]
@@ -626,12 +776,46 @@ version = "0.2.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"

+[[package]]
+name = "valuable"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"

+[[package]]
+name = "wasip2"
+version = "1.0.1+wasi-0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -721,6 +905,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"

+[[package]]
+name = "wit-bindgen"
+version = "0.46.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
+
 [[package]]
 name = "zmij"
 version = "0.1.8"
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "mock-server"
+name = "mock_server"
 version = "0.1.0"
 edition = "2024"

@@ -18,7 +18,10 @@ serde_yaml = "0.9.34+deprecated"
 serde_json = "1.0.147"

 # 物理目录递归扫描工具
-#walkdir = "2.5.0"
+walkdir = "2.5.0"
+
+tracing="0.1.44"
+tracing-subscriber = "0.3.22"

 # 性能优化：快速哈希（可选，用于路由匹配）
 #dashmap = "7.0.0-rc2"
@@ -26,3 +29,6 @@ serde_json = "1.0.147"
 #notify = "8.2.0"
 # 路径处理
 #pathdiff = "0.2.3"
+
+[dev-dependencies]
+tempfile = "3.24.0"
--- a/mocks/v1/auth/login.yaml
+++ b/mocks/v1/auth/login.yaml
@@ -0,0 +1,23 @@
+id: "auth_login_001"
+request:
+  method: "POST"
+  path: "/api/v1/auth/login"
+  # 必须包含此 Header 才会匹配
+  headers:
+    Content-Type: "application/json"
+    Authorization: "111"
+    host: "127.0.0.1:8080"
+response:
+  status: 200
+  headers:
+    Content-Type: "application/json"
+    X-Mock-Engine: "Rust-Gemini-v1.2"
+  # 直接内联 JSON 字符串
+  body: >
+    {
+      "code": 0,
+      "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6" },
+      "msg": "success"
+    }
+settings:
+  delay_ms: 200 # 模拟真实网络延迟
--- a/mocks/v1/products/export.yaml
+++ b/mocks/v1/products/export.yaml
@@ -0,0 +1,11 @@
+id: "prod_export_pdf"
+request:
+  method: "GET"
+  path: "/api/v1/products/report"
+response:
+  status: 200
+  headers:
+    Content-Type: "application/pdf"
+    Content-Disposition: "attachment; filename=report.pdf"
+  # 智能协议：引擎会自动识别前缀并异步读取磁盘文件
+  body: "file://./storage/reports/annual_2024.pdf"
--- a/mocks/v1/system/health.yaml
+++ b/mocks/v1/system/health.yaml
@@ -0,0 +1,16 @@
+# 使用 YAML 数组语法定义多个规则
+- id: "sys_ping"
+  request:
+    method: "GET"
+    path: "/api/v1/ping"
+  response:
+    status: 200
+    body: "pong"
+
+- id: "sys_version"
+  request:
+    method: "GET"
+    path: "/api/v1/version"
+  response:
+    status: 200
+    body: '{"version": "1.2.0-smart"}'
--- a/mocks/v1/user/search.yaml
+++ b/mocks/v1/user/search.yaml
@@ -0,0 +1,11 @@
+id: "user_search_admin"
+request:
+  method: "GET"
+  path: "/api/v1/users"
+  # 请求中必须包含 role=admin 且 status=active
+  query_params:
+    role: "admin"
+    status: "active"
+response:
+  status: 200
+  body: '{"users": [{"id": 1, "name": "SuperAdmin"}]}'
--- a/src/config.rs
+++ b/src/config.rs
@@ -0,0 +1,74 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// 顶层包装：支持单对象或数组，自动打平
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+pub enum MockSource {
+    /// 对应“一接口一文件”模式
+    Single(MockRule),
+    /// 对应“一文件多接口”模式
+    Multiple(Vec<MockRule>),
+}
+
+impl MockSource {
+    /// 将不同的解析模式统一转化为列表，供 Loader 构建索引
+    pub fn flatten(self) -> Vec<MockRule> {
+        match self {
+            Self::Single(rule) => vec![rule],
+            Self::Multiple(rules) => rules,
+        }
+    }
+}
+
+/// 核心 Mock 规则定义
+#[derive(Debug, Deserialize,Serialize, Clone,PartialEq)]
+pub struct MockRule {
+    pub id: String,
+    pub request: RequestMatcher,
+    pub response: MockResponse,
+    pub settings: Option<MockSettings>,
+}
+
+/// 请求匹配条件
+#[derive(Debug, Deserialize,Serialize, Clone,PartialEq)]
+pub struct RequestMatcher {
+    pub method: String,
+    pub path: String,
+    /// 选填：只有请求包含这些参数时才匹配
+    pub query_params: Option<HashMap<String, String>>,
+    /// 选填：只有请求包含这些 Header 时才匹配
+    pub headers: Option<HashMap<String, String>>,
+}
+
+/// 响应内容定义
+#[derive(Debug, Deserialize,Serialize, Clone,PartialEq)]
+pub struct MockResponse {
+    pub status: u16,
+    pub headers: Option<HashMap<String, String>>,
+    /// 统一字段：支持 Inline 文本或 file:// 前缀的路径
+    pub body: String,
+}
+
+/// 模拟器行为设置
+#[derive(Debug, Deserialize,Serialize, Clone,PartialEq)]
+pub struct MockSettings {
+    /// 模拟网络延迟（毫秒）
+    pub delay_ms: Option<u64>,
+}
+
+impl MockResponse {
+    /// 辅助方法：判断是否为文件协议
+    pub fn is_file_protocol(&self) -> bool {
+        self.body.starts_with("file://")
+    }
+
+    /// 获取去掉协议前缀后的纯物理路径
+    pub fn get_file_path(&self) -> Option<&str> {
+        if self.is_file_protocol() {
+            Some(&self.body[7..]) // 截取 "file://" 之后的内容
+        } else {
+            None
+        }
+    }
+}
--- a/src/handler.rs
+++ b/src/handler.rs
@@ -0,0 +1,87 @@
+use axum::{
+    body::Body,
+    extract::{Query, State},
+    http::{HeaderMap, Method, Request, StatusCode},
+    response::{IntoResponse, Response},
+};
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio_util::io::ReaderStream; // 需在 Cargo.toml 确认有 tokio-util
+
+use crate::router::MockRouter;
+
+/// 共享的应用状态
+pub struct AppState {
+    pub router: MockRouter,
+}
+
+/// 全局统一请求处理函数
+pub async fn mock_handler(
+    State(state): State<Arc<AppState>>,
+    method: Method,
+    headers: HeaderMap,
+    Query(params): Query<HashMap<String, String>>,
+    req: Request<Body>,
+) -> impl IntoResponse {
+    let path = req.uri().path();
+
+    // 1. 将 Axum HeaderMap 转换为简单的 HashMap 供 Router 使用
+    let mut req_headers = HashMap::new();
+    for (name, value) in headers.iter() {
+        if let Ok(v) = value.to_str() {
+            req_headers.insert(name.as_str().to_string(), v.to_string());
+        }
+    }
+
+    // 2. 执行匹配逻辑
+    if let Some(rule) = state.router.match_rule(method.as_str(), path, &params, &req_headers) {
+
+        // 3. 处理模拟延迟
+        if let Some(ref settings) = rule.settings {
+            if let Some(delay) = settings.delay_ms {
+                tokio::time::sleep(std::time::Duration::from_millis(delay)).await;
+            }
+        }
+
+        // 4. 构建响应基础信息
+        let status = StatusCode::from_u16(rule.response.status).unwrap_or(StatusCode::OK);
+        let mut response_builder = Response::builder().status(status);
+
+        // 注入 YAML 定义的 Header
+        if let Some(ref h) = rule.response.headers {
+
+            for (k, v) in h {
+                // println!("{}:{}",k.clone(), v.clone());
+                response_builder = response_builder.header(k, v);
+            }
+        }
+
+        // 5. 执行 Smart Body 协议逻辑
+        if let Some(file_path) = rule.response.get_file_path() {
+            // A. 文件模式：异步打开文件并转换为流，实现低内存占用
+            match tokio::fs::File::open(file_path).await {
+                Ok(file) => {
+                    let stream = ReaderStream::new(file);
+                    let body = Body::from_stream(stream);
+                    response_builder.body(body).unwrap()
+                }
+                Err(_) => {
+                    Response::builder()
+                        .status(StatusCode::INTERNAL_SERVER_ERROR)
+                        .body(Body::from(format!("Mock Error: File not found at {}", file_path)))
+                        .unwrap()
+                }
+            }
+        } else {
+            // B. 内联模式：直接返回字符串内容
+            response_builder.body(Body::from(rule.response.body.clone())).unwrap()
+        }
+    } else {
+        println!("请求头{:?}",req_headers.clone());
+        // 匹配失败返回 404
+        Response::builder()
+            .status(StatusCode::NOT_FOUND)
+            .body(Body::from("No mock rule matched this request"))
+            .unwrap()
+    }
+}
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -0,0 +1,5 @@
+// 声明模块并设为 pub，这样 tests/ 目录才能看到它们
+pub mod config;
+pub mod loader;
+pub mod router;
+pub mod handler;
--- a/src/loader.rs
+++ b/src/loader.rs
@@ -0,0 +1,58 @@
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use walkdir::WalkDir; // 需在 Cargo.toml 添加 walkdir 依赖
+
+use crate::config::{MockRule, MockSource}; // 假设 config.rs 中定义了这两个类型
+
+pub struct MockLoader;
+
+impl MockLoader {
+    /// 递归扫描指定目录并构建索引表
+    pub fn load_all_from_dir(dir: &Path) -> HashMap<String, Vec<MockRule>> {
+        let mut index: HashMap<String, Vec<MockRule>> = HashMap::new();
+
+        // 1. 使用 walkdir 递归遍历目录，不限层级
+        for entry in WalkDir::new(dir)
+            .into_iter()
+            .filter_map(|e| e.ok())
+            .filter(|e| e.path().extension().map_or(false, |ext| ext == "yaml" || ext == "yml"))
+        {
+            if let Some(rules) = Self::parse_yaml_file(entry.path()) {
+                for rule in rules {
+                    // 2. 提取路径首段作为索引 Key
+                    let key = Self::extract_first_segment(&rule.request.path);
+
+                    // 3. 将规则插入到对应的索引桶中
+                    index.entry(key).or_insert_with(Vec::new).push(rule);
+                }
+            }
+        }
+
+        println!("Successfully loaded {} segments from {:?}", index.len(), dir);
+        index
+    }
+
+    /// 解析单个 YAML 文件，支持单接口和多接口模式
+    fn parse_yaml_file(path: &Path) -> Option<Vec<MockRule>> {
+        let content = fs::read_to_string(path).ok()?;
+
+        // 利用 serde_yaml 的反序列化能力处理 MockSource 枚举
+        match serde_yaml::from_str::<MockSource>(&content) {
+            Ok(source) => Some(source.flatten()), // 统一打平为 Vec<MockRule>
+            Err(e) => {
+                eprintln!("Failed to parse YAML at {:?}: {}", path, e);
+                None
+            }
+        }
+    }
+
+    /// 提取路径的第一级作为 Key（例如 "/api/v1/login" -> "api"）
+    fn extract_first_segment(path: &str) -> String {
+        path.trim_start_matches('/')
+            .split('/')
+            .next()
+            .unwrap_or("root") // 如果是根路径 "/"，则归类到 "root"
+            .to_string()
+    }
+}
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,3 +1,44 @@
-fn main() {
-    println!("Hello, mock-server!");
+use std::net::SocketAddr;
+use std::path::Path;
+use std::sync::Arc;
+use axum::{routing::any, Router};
+use mock_server::loader::MockLoader;
+use mock_server::router::MockRouter;
+use mock_server::handler::{mock_handler, AppState};
+
+#[tokio::main]
+async fn main() {
+    // 1. 初始化日志（建议添加，方便观察加载情况）
+    // 需要在 Cargo.toml 添加 tracing-subscriber = "0.3"
+    tracing_subscriber::fmt::init();
+
+    // 2. 递归加载所有的 YAML 配置文件
+    let mocks_dir = Path::new("./mocks");
+    if !mocks_dir.exists() {
+        println!("Warning: 'mocks/' directory not found. Creating it...");
+        std::fs::create_dir_all(mocks_dir).unwrap();
+    }
+
+    println!("Scanning mocks directory...");
+    let index = MockLoader::load_all_from_dir(mocks_dir);
+
+    // 3. 构建路由引擎并包装为共享状态
+    let router_engine = MockRouter::new(index);
+    let shared_state = Arc::new(AppState {
+        router: router_engine,
+    });
+
+    // 4. 配置 Axum 路由
+    // 使用 any(mock_handler) 意味着它会接管所有 HTTP 方法和所有路径的请求
+    let app = Router::new()
+        .fallback(any(mock_handler))
+        .with_state(shared_state);
+
+    // 5. 启动服务
+    let addr = SocketAddr::from(([127, 0, 0, 1], 8080));
+    println!("🚀 Rust Mock Server is running on http://{}", addr);
+    println!("Ready to handle requests based on your YAML definitions.");
+
+    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
+    axum::serve(listener, app).await.unwrap();
 }
--- a/src/router.rs
+++ b/src/router.rs
@@ -0,0 +1,93 @@
+use std::collections::HashMap;
+use crate::config::MockRule;
+
+pub struct MockRouter {
+    // 索引表：Key 是路径首段（如 "api"），Value 是该段下的所有 Mock 规则
+    pub index: HashMap<String, Vec<MockRule>>,
+}
+
+impl MockRouter {
+    pub fn new(index: HashMap<String, Vec<MockRule>>) -> Self {
+        Self { index }
+    }
+
+    /// 核心匹配函数：根据请求信息寻找匹配的 Mock 规则
+    pub fn match_rule(
+        &self,
+        method: &str,
+        path: &str,
+        queries: &HashMap<String, String>,
+        headers: &HashMap<String, String>,
+    ) -> Option<&MockRule> {
+        // 1. 提取请求路径的首段作为索引 Key
+        let key = self.extract_first_segment(path);
+        println!("DEBUG: Request Key: '{}', Available Keys: {:?}", key, self.index.keys());
+        // 2. 从 HashMap 中快速定位候选规则列表 (O(k) 复杂度)
+        if let Some(rules) = self.index.get(&key) {
+            // 3. 在候选集中进行线性深度匹配
+            for rule in rules {
+                if self.is_match(rule, method, path, queries, headers) {
+                    return Some(rule);
+                }
+            }
+        }
+
+        None
+    }
+
+    /// 细粒度匹配逻辑
+    fn is_match(
+        &self,
+        rule: &MockRule,
+        method: &str,
+        path: &str,
+        queries: &HashMap<String, String>,
+        headers: &HashMap<String, String>,
+    ) -> bool {
+        // A. 基础校验：Method 和 Path 必须完全一致 (忽略末尾斜杠)
+        if rule.request.method.to_uppercase() != method.to_uppercase() {
+            println!("DEBUG: [ID:{}] Method Mismatch: YAML={}, Req={}", rule.id, rule.request.method, method);
+            return false;
+        }
+        if rule.request.path.trim_end_matches('/') != path.trim_end_matches('/') {
+            println!("DEBUG: [ID:{}] Path Mismatch: YAML='{}', Req='{}'", rule.id, rule.request.path, path);
+            return false;
+        }
+        println!("DEBUG: [ID:{}] Method and Path matched! Checking headers...", rule.id);
+        // B. Query 参数校验 (子集匹配原则)
+        if let Some(ref required_queries) = rule.request.query_params {
+            for (key, val) in required_queries {
+                if queries.get(key) != Some(val) {
+                    return false;
+                }
+            }
+        }
+        
+        // C. Header 校验 (优化版)
+        if let Some(ref required_headers) = rule.request.headers {
+            for (key, val) in required_headers {
+                println!("{}:{}",key.clone(), val.clone());
+                // 方案：将 Key 统一转为小写比较，并检查请求头是否“包含”期望的值
+                let matched = headers.iter().any(|(k, v)| {
+                    // k.to_lowercase() == key.to_lowercase() && v.contains(val)
+                    k.to_lowercase() == key.to_lowercase() && v==val
+                });
+
+                if !matched {
+                    return false;
+                }
+            }
+        }
+
+        true
+    }
+
+    /// 与 Loader 保持一致的 Key 提取算法
+    fn extract_first_segment(&self, path: &str) -> String {
+        path.trim_start_matches('/')
+            .split('/')
+            .next()
+            .unwrap_or("root")
+            .to_string()
+    }
+}
--- a/tests/integration_test.rs
+++ b/tests/integration_test.rs
@@ -0,0 +1,147 @@
+use std::fs::{self, File};
+use std::io::Write;
+use tempfile::tempdir;
+// 替换为你的项目实际名称
+use mock_server::config::{MockRule, MockSource};
+use mock_server::loader::MockLoader;
+use mock_server::router::MockRouter;
+use std::collections::HashMap;
+
+/// 模块一：验证 Config 反序列化逻辑
+#[test]
+fn test_config_parsing_scenarios() {
+    // 场景 A: 验证单接口配置 (Inline 模式)
+    let yaml_single = r#"
+        id: "auth_v1"
+        request: { method: "POST", path: "/api/v1/login" }
+        response: { status: 200, body: "welcome" }
+    "#;
+    let source_s: MockSource = serde_yaml::from_str(yaml_single).expect("解析单接口失败");
+    let rules = source_s.flatten();
+    assert_eq!(rules.len(), 1);
+    assert_eq!(rules[0].request.path, "/api/v1/login");
+
+    // 场景 B: 验证多接口配置 (Collection 模式)
+    let yaml_multi = r#"
+        - id: "api_1"
+          request: { method: "GET", path: "/health" }
+          response: { status: 200, body: "ok" }
+        - id: "api_2"
+          request: { method: "GET", path: "/version" }
+          response: { status: 200, body: "1.0" }
+    "#;
+    let source_m: MockSource = serde_yaml::from_str(yaml_multi).expect("解析多接口失败");
+    assert_eq!(source_m.flatten().len(), 2);
+
+    // 场景 C: 验证 Smart Body 的 file:// 协议字符串解析
+    let yaml_file = r#"
+        id: "export_api"
+        request: { method: "GET", path: "/download" }
+        response: { status: 200, body: "file://./storage/data.zip" }
+    "#;
+    let source_f: MockSource = serde_yaml::from_str(yaml_file).unwrap();
+    let rule = &source_f.flatten()[0];
+    assert!(rule.response.body.starts_with("file://"));
+}
+
+/// 模块二：验证 Loader 递归扫描与索引构建
+#[test]
+fn test_loader_recursive_indexing() {
+    let temp_root = tempdir().expect("无法创建临时目录");
+    let root_path = temp_root.path();
+
+    // 创建多级目录结构
+    let auth_path = root_path.join("v1/auth");
+    fs::create_dir_all(&auth_path).unwrap();
+
+    // 1. 在深层目录写入一个单接口文件
+    let mut f1 = File::create(auth_path.join("login.yaml")).unwrap();
+    writeln!(f1, "id: 'l1'\nrequest: {{ method: 'POST', path: '/api/v1/login' }}\nresponse: {{ status: 200, body: 'ok' }}").unwrap();
+
+    // 2. 在根目录写入一个多接口文件
+    let mut f2 = File::create(root_path.join("sys.yaml")).unwrap();
+    writeln!(f2, "- id: 's1'\n  request: {{ method: 'GET', path: '/health' }}\n  response: {{ status: 200, body: 'up' }}").unwrap();
+
+    // 执行加载
+    let index = MockLoader::load_all_from_dir(root_path);
+
+    // 验证逻辑：
+    // 即使物理路径很深，索引 Key 必须是逻辑路径的首段
+    assert!(
+        index.contains_key("api"),
+        "必须通过 /api/v1/login 提取出 'api' 键"
+    );
+    assert!(
+        index.contains_key("health"),
+        "必须通过 /health 提取出 'health' 键"
+    );
+
+    // 验证扁平化后的总数
+    let total: usize = index.values().map(|v| v.len()).sum();
+    assert_eq!(total, 2);
+}
+
+#[test]
+fn test_router_matching_logic() {
+    // 1. 准备模拟数据（模拟 Loader 的输出）
+    let mut index = HashMap::new();
+
+    let rule_auth = serde_yaml::from_str::<MockSource>(
+        r#"
+        id: "auth_v1"
+        request:
+          method: "POST"
+          path: "/api/v1/login"
+          headers: { "Content-Type": "application/json" }
+        response: { status: 200, body: "token_123" }
+    "#,
+    )
+    .unwrap()
+    .flatten();
+
+    let rule_user = serde_yaml::from_str::<MockSource>(
+        r#"
+        id: "get_user"
+        request:
+          method: "GET"
+          path: "/api/user/info"
+          query_params: { "id": "100" }
+        response: { status: 200, body: "user_info" }
+    "#,
+    )
+    .unwrap()
+    .flatten();
+
+    // 构建 HashMap 索引（模仿 Loader 的行为）
+    index.insert(
+        "api".to_string(),
+        vec![rule_auth[0].clone(), rule_user[0].clone()],
+    );
+
+    let router = MockRouter::new(index);
+
+    // 2. 测试场景 A：完全匹配
+    let mut headers = HashMap::new();
+    headers.insert("Content-Type".to_string(), "application/json".to_string());
+
+    let matched = router.match_rule("POST", "/api/v1/login", &HashMap::new(), &headers);
+    assert!(matched.is_some());
+    assert_eq!(matched.unwrap().id, "auth_v1");
+
+    // 3. 测试场景 B：路径末尾斜杠归一化 (Trailing Slash)
+    let matched_slash = router.match_rule("POST", "/api/v1/login/", &HashMap::new(), &headers);
+    assert!(matched_slash.is_some(), "应该忽略路径末尾的斜杠");
+
+    // 4. 测试场景 C：Query 参数子集匹配
+    let mut queries = HashMap::new();
+    queries.insert("id".to_string(), "100".to_string());
+    queries.insert("extra".to_string(), "unused".to_string()); // 额外的参数不应影响匹配
+
+    let matched_query = router.match_rule("GET", "/api/user/info", &queries, &HashMap::new());
+    assert!(matched_query.is_some());
+    assert_eq!(matched_query.unwrap().id, "get_user");
+
+    // 5. 测试场景 D：匹配失败（Method 错误）
+    let fail_method = router.match_rule("GET", "/api/v1/login", &HashMap::new(), &headers);
+    assert!(fail_method.is_none());
+}
--- a/tests/loader_test.rs
+++ b/tests/loader_test.rs
@@ -0,0 +1,114 @@
+use std::fs::{self, File};
+use std::io::Write;
+use tempfile::tempdir;
+// 假设你的项目名在 Cargo.toml 中叫 mock_server
+use mock_server::config::MockSource;
+use mock_server::loader::MockLoader;
+
+#[test]
+fn test_config_deserialization() {
+    // 测试 1：验证单接口 YAML 解析
+    let single_yaml = r#"
+        id: "auth_v1"
+        request:
+          method: "POST"
+          path: "/api/v1/login"
+        response:
+          status: 200
+          body: "inline_content"
+    "#;
+    let res: MockSource = serde_yaml::from_str(single_yaml).expect("应该成功解析单接口");
+    assert_eq!(res.flatten().len(), 1);
+    // assert_eq!(res.flatten()[0].id, "auth_v1");
+
+    // 测试 2：验证多接口 YAML 数组解析
+    let multi_yaml = r#"
+        - id: "api_1"
+          request: { method: "GET", path: "/1" }
+          response: { status: 200, body: "b1" }
+        - id: "api_2"
+          request: { method: "GET", path: "/2" }
+          response: { status: 200, body: "b2" }
+    "#;
+    let res_multi: MockSource = serde_yaml::from_str(multi_yaml).expect("应该成功解析接口数组");
+    assert_eq!(res_multi.flatten().len(), 2);
+}
+
+#[test]
+fn test_recursive_loading_logic() {
+    // 创建临时 Mock 目录结构
+    let root_dir = tempdir().expect("创建临时目录失败");
+    let root_path = root_dir.path();
+
+    // 构造物理层级：mocks/v1/user/
+    let user_dir = root_path.join("v1/user");
+    fs::create_dir_all(&user_dir).unwrap();
+
+    // 在深层目录创建单接口文件
+    let mut file1 = File::create(user_dir.join("get_profile.yaml")).unwrap();
+    writeln!(
+        file1,
+        r#"
+        id: "user_profile"
+        request:
+          method: "GET"
+          path: "/api/v1/user/profile"
+        response:
+          status: 200
+          body: "profile_data"
+    "#
+    )
+    .unwrap();
+
+    // 在根目录创建多接口文件
+    let mut file2 = File::create(root_path.join("system.yaml")).unwrap();
+    writeln!(
+        file2,
+        r#"
+        - id: "sys_health"
+          request: {{ method: "GET", path: "/health" }}
+          response: {{ status: 200, body: "ok" }}
+        - id: "sys_version"
+          request: {{ method: "GET", path: "/version" }}
+          response: {{ status: 200, body: "1.0.0" }}
+    "#
+    )
+    .unwrap();
+//     writeln!(
+//         file2,
+//         r#"
+// - id: "sys_health"
+//   request:
+//     method: "GET"
+//     path: "/health"
+//   response:
+//     status: 200
+//     body: "ok"
+// - id: "sys_version"
+//   request:
+//     method: "GET"
+//     path: "/version"
+//   response:
+//     status: 200
+//     body: "1.0.0"
+// "#
+//     )
+//     .unwrap();
+
+    // 执行加载
+    let index = MockLoader::load_all_from_dir(root_path);
+
+    // 断言结果：
+    // 1. 检查 Key 是否根据路径首段正确提取（/api/v1/... -> api, /health -> health）
+    assert!(index.contains_key("api"), "索引应包含 'api' 键");
+    assert!(index.contains_key("health"), "索引应包含 'health' 键");
+    assert!(index.contains_key("version"), "索引应包含 'version' 键");
+
+    // 2. 检查规则总数
+    let total_rules: usize = index.values().map(|v| v.len()).sum();
+    assert_eq!(total_rules, 3, "总规则数应为 3");
+
+    // 3. 检查深层文件是否被正确读取
+    let api_rules = &index["api"];
+    assert_eq!(api_rules[0].id, "user_profile");
+}