请求生命周期

理解 Mock 请求的处理流程，有助于你更好地排查问题和优化配置。

概述

当浏览器发起一个请求时，插件会按照以下流程处理：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   请求进入  │ -> │  路径匹配   │ -> │  验证处理   │ -> │  响应生成   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │                  │
       v                  v                  v                  v
  解析请求信息       查找 Mock 配置      执行验证器        返回 Mock 数据
  (URL/Method/       按优先级排序        检查条件          或转发到后端
   Headers/Body)

详细流程

1. 请求进入阶段

处理内容：

• 接收 HTTP 请求
• 解析 URL、Method、Headers
• 解析请求体（Body）
• 解析 Cookies

关键代码：

// 请求信息会自动解析到 request 对象
export default defineMock({
  url: '/api/users',
  body: request => ({
    // request 包含以下信息：
    method: request.method, // 'GET'
    url: request.url, // '/api/users?page=1'
    query: request.query, // { page: '1' }
    headers: request.headers, // { 'content-type': 'application/json' }
    body: request.body, // POST/PUT 请求体
    params: request.params, // 路由参数
    getCookie: request.getCookie // 获取 Cookie 的方法
  })
})

2. 路径匹配阶段

处理内容：

• 检查请求路径是否匹配 prefix 配置
• 遍历所有 Mock 配置进行匹配
• 按优先级排序匹配结果

匹配优先级：

1. 前缀匹配：请求路径必须以 prefix 开头

   mockDevServerPlugin({
     prefix: ['/api', '/mock'] // 只处理这些前缀的请求
   })

2. URL 匹配：使用 path-to-regexp 匹配 url 配置

   export default defineMock({
     url: '/api/users/:id', // 匹配 /api/users/123
     body: ({ params }) => ({ id: params.id })
   })

3. Method 匹配：检查 HTTP 方法是否匹配

   export default defineMock({
     url: '/api/users',
     method: ['GET', 'POST'], // 只匹配 GET 和 POST
     body: { list: [] }
   })

3. 验证处理阶段

处理内容：

• 执行 validator 验证器
• 检查请求参数、查询字符串、请求体
• 确定最终匹配的 Mock 配置

验证器类型：

// 1. 对象验证 - 精确匹配
export default defineMock({
  url: '/api/search',
  validator: { query: { type: 'user' } },
  body: { result: 'users' }
})

// 2. 函数验证 - 自定义逻辑
export default defineMock({
  url: '/api/data',
  validator: (request) => {
    return request.headers['x-role'] === 'admin'
  },
  body: { sensitive: 'data' }
})

4. 响应生成阶段

处理内容：

• 执行 body 函数或 response 函数
• 设置响应状态码、响应头、Cookies
• 返回响应数据

响应类型：

// 1. 静态响应
export default defineMock({
  url: '/api/static',
  status: 200,
  headers: { 'x-custom': 'value' },
  body: { message: 'ok' }
})

// 2. 动态响应
export default defineMock({
  url: '/api/dynamic',
  body: ({ query, params }) => ({
    page: query.page,
    id: params.id
  })
})

// 3. 自定义响应
export default defineMock({
  url: '/api/custom',
  response: (req, res) => {
    res.statusCode = 201
    res.setHeader('Content-Type', 'application/json')
    res.end(JSON.stringify({ custom: true }))
  }
})

WebSocket 生命周期

WebSocket 连接有独立的生命周期：

连接建立 -> 消息处理 -> 连接关闭
    |           |            |
    v           v            v
  upgrade    message      cleanup
  协议升级   双向通信     资源清理

WebSocket 处理流程

export default defineMock({
  url: '/ws/chat',
  ws: true,
  setup(wss, { onCleanup }) {
    // 1. 连接建立阶段
    wss.on('connection', (ws, req) => {
      console.log('Client connected')

      // 2. 消息处理阶段
      ws.on('message', (data) => {
        // 处理消息并广播
        wss.clients.forEach((client) => {
          if (client.readyState === 1) {
            client.send(data)
          }
        })
      })

      // 3. 连接关闭阶段
      ws.on('close', () => {
        console.log('Client disconnected')
      })
    })

    // 4. 清理阶段（热更新时触发）
    onCleanup(() => {
      console.log('Cleaning up WebSocket server')
    })
  }
})

热更新机制

Mock 文件热更新

当 Mock 文件修改时：

1. 文件监听：插件监听 mock 目录下的文件变化
2. 重新加载：重新编译修改的 Mock 文件
3. 缓存更新：更新 Mock 配置缓存
4. 页面刷新（可选）：如果配置了 reload: true，刷新页面

mockDevServerPlugin({
  reload: false // 默认 false，热更新不刷新页面
})

数据持久化

使用 defineMockData 可以在热更新时保持数据：

import { defineMock, defineMockData } from 'vite-plugin-mock-dev-server'

// 数据在热更新时会被保留
const users = defineMockData('users', [])

export default defineMock({
  url: '/api/users',
  body: () => users.value // 热更新后数据仍然存在
})

调试生命周期

开启调试日志

mockDevServerPlugin({
  log: 'debug'
})

自定义调试信息

export default defineMock({
  url: '/api/debug',
  body: (request) => {
    console.log('[Debug] Request:', {
      method: request.method,
      url: request.url,
      query: request.query,
      body: request.body
    })
    return { debug: true }
  }
})