whistle.mockbubu 2.1.5 → 2.2.0-beta.1

package/lib/config/const.js

@@ -136,3 +136,14 @@ exports.PLUGIN_MODE = {
  * 默认插件模式
  */
 exports.DEFAULT_PLUGIN_MODE = 'default'
+
+// ============================================
+// 条件匹配模式相关常量
+// ============================================
+
+/**
+ * mockVersion 的特殊值：表示启用条件匹配模式
+ * 当 file.json 中 config.mockVersion === MATCH_MODE_VALUE 时，
+ * 后端进入条件匹配流程（读取 match_versions/ 目录中的规则）
+ */
+exports.MATCH_MODE_VALUE = '__match_mode__'

package/lib/core/server-entry/response-handler.js

@@ -3,10 +3,13 @@
  * 功能: Mock 响应返回逻辑
  * 职责:
  * - 返回 Mock 数据 (源数据或版本数据)
+ * - 条件匹配模式下匹配规则并返回对应数据
  * - 处理版本切换
  * - 处理响应头
  */
 
+const { MATCH_MODE_VALUE } = require('../../config/const')
+
 /**
  * 返回 Mock 响应数据
  * @param {Object} res - Whistle 响应对象
@@ -16,38 +19,224 @@
  * @param {Object} options.groupManager - 组管理器实例
  * @param {string} options.currentGroupId - 当前组ID
  * @param {string} options.filename - 文件名
+ * @param {Object} options.originalReq - Whistle 原始请求对象（用于条件匹配）
  */
 async function sendMockResponse(res, sourceData, options = {}) {
-  const { mockVersion, groupManager, currentGroupId, filename } = options
+  const { mockVersion, groupManager, currentGroupId, filename, originalReq } = options
 
   // 解析源数据 (storageAdapter.readFile 返回的是 session 对象的 JSON 字符串)
   const session = JSON.parse(sourceData)
   const sourceResponse = session?.res
-  const { statusCode, statusMessage, headers } = sourceResponse
+  const { statusCode, statusMessage } = sourceResponse
 
-  // 设置响应头标记 (来自 Mock)
+  // 浅拷贝 headers，避免直接修改 session 对象（若未来引入缓存会产生副作用）
+  const headers = { ...sourceResponse.headers }
   headers['from-mockbubu-source'] = 'true'
   headers['x-mockbubu-mocked'] = 'true'
   delete headers['content-encoding']
   delete headers['content-length']
 
-  res.writeHead(statusCode, statusMessage, headers)
+  // 【条件匹配模式】
+  if (mockVersion === MATCH_MODE_VALUE) {
+    const matchResult = await matchByConditions({
+      groupManager,
+      currentGroupId,
+      filename,
+      originalReq,
+    })
+
+    headers['x-mockbubu-match-mode'] = 'match'
 
-  // 检查是否需要使用版本数据 (用户编辑的 Mock 数据)
+    if (matchResult.matched) {
+      // header 值必须为 ASCII，对中文规则名做 encodeURIComponent 编码
+      headers['x-mockbubu-match-rule'] = encodeURIComponent(matchResult.ruleName || '')
+      headers['x-mockbubu-match-params'] = encodeURIComponent(matchResult.paramsSummary || '')
+      res.writeHead(statusCode, statusMessage, headers)
+      res.end(JSON.stringify(matchResult.content ?? {}))
+      return
+    }
+
+    // 全不命中 → 通知调用方透传请求，不返回 mock 数据
+    return { action: 'passthrough' }
+  }
+
+  // 【版本直选模式】先确认版本数据是否存在，再统一调用 writeHead
   if (mockVersion && groupManager && currentGroupId && filename) {
     const versionData = await groupManager.getGroupVersionContent(currentGroupId, filename, mockVersion)
     if (versionData) {
-      // 返回版本数据
+      res.writeHead(statusCode, statusMessage, headers)
       res.end(JSON.stringify(versionData))
       return
     }
     // 版本不存在时降级到源数据
   }
 
-  // 返回源数据 (原始捕获的响应体)
+  res.writeHead(statusCode, statusMessage, headers)
   res.end(sourceResponse.body)
 }
 
+/**
+ * 条件匹配核心逻辑
+ *
+ * 匹配规则：
+ * 1. 按条件数量降序（条件越多优先级越高）
+ * 2. 条件数量相同时按 priority 字段升序（数字越小越优先）
+ * 3. 空条件规则作为兜底，最后匹配
+ * 4. 全不命中时返回 matched: false，由调用方降级到 source
+ *
+ * @param {Object} params
+ * @param {Object} params.groupManager - 组管理器
+ * @param {string} params.currentGroupId - 当前组ID
+ * @param {string} params.filename - 文件名（URL）
+ * @param {Object} params.originalReq - Whistle 原始请求对象
+ * @returns {{ matched: boolean, content?, ruleName?, paramsSummary? }}
+ */
+async function matchByConditions(params) {
+  const { groupManager, currentGroupId, filename, originalReq } = params
+
+  // 获取所有匹配规则（storage 层已按 priority 排序）
+  const matchVersions = await groupManager.getMatchVersions(currentGroupId, filename)
+  if (!matchVersions || matchVersions.length === 0) {
+    return { matched: false }
+  }
+
+  // 提取当前请求参数
+  const queryParams = extractQueryParams(originalReq)
+  const payloadParams = extractPayloadParams(originalReq)
+
+  // 按条件数量降序 + priority 升序排序（条件越多越具体，优先匹配）
+  // storage 层已按 priority 排序，这里再按 conditions.length 降序叠加
+  const sorted = [...matchVersions].sort((a, b) => {
+    const condDiff = (b.conditions?.length || 0) - (a.conditions?.length || 0)
+    if (condDiff !== 0) return condDiff
+    return (a.priority || 0) - (b.priority || 0)
+  })
+
+  let fallbackRule = null
+
+  // 逐条匹配（AND 关系：所有条件必须同时满足）
+  for (const rule of sorted) {
+    if (!rule.conditions || rule.conditions.length === 0) {
+      // 空条件规则作为兜底，记录备用
+      if (!fallbackRule) fallbackRule = rule
+      continue
+    }
+
+    const allMatch = rule.conditions.every((cond) => {
+      const sourceParams = cond.source === 'query' ? queryParams : payloadParams
+      // 精确匹配：参数名和参数值必须完全相等（都转为字符串比较）
+      return String(sourceParams[cond.key]) === String(cond.value)
+    })
+
+    if (allMatch) {
+      return {
+        matched: true,
+        content: rule.content ?? {},
+        ruleName: rule.name,
+        paramsSummary: rule.conditions
+          .map(c => `${c.source}.${c.key}=${c.value}`)
+          .join(', '),
+      }
+    }
+  }
+
+  // 尝试兜底规则（空条件规则）
+  if (fallbackRule) {
+    return {
+      matched: true,
+      content: fallbackRule.content ?? {},
+      ruleName: fallbackRule.name,
+      paramsSummary: '(default)',
+    }
+  }
+
+  return { matched: false }
+}
+
+/**
+ * 从原始请求中提取 query 参数
+ * 来源：req.originalReq.url，fallback 到 x-whistle-full-url header
+ *
+ * @param {Object} originalReq - Whistle 原始请求对象
+ * @returns {Object} query 参数 key-value 对
+ */
+function extractQueryParams(originalReq) {
+  if (!originalReq) return {}
+
+  try {
+    // 某些 Whistle 代理场景（tunnel/HTTP2）下 originalReq.url 可能不含 query，
+    // 完整 URL 会在 x-whistle-full-url header 里（URL 编码格式）
+    const fullUrlHeader = originalReq.headers?.['x-whistle-full-url']
+    const rawUrl = originalReq.url ||
+      (fullUrlHeader ? decodeURIComponent(fullUrlHeader) : '') ||
+      ''
+    const url = new URL(rawUrl)
+    const params = {}
+    url.searchParams.forEach((value, key) => {
+      params[key] = value
+    })
+    return params
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 从原始请求中提取 payload 参数（仅支持 JSON，只提取第一层 key-value）
+ * 来源：req.originalReq.body
+ *
+ * 非 JSON payload 时返回空对象，条件匹配只会比较 query 部分。
+ *
+ * @param {Object} originalReq - Whistle 原始请求对象
+ * @returns {Object} payload 参数 key-value 对（值统一转为字符串）
+ */
+function extractPayloadParams(originalReq) {
+  if (!originalReq) return {}
+
+  try {
+    let body = originalReq.body || ''
+
+    // Buffer 转字符串
+    if (Buffer.isBuffer(body)) {
+      body = body.toString('utf8')
+    }
+
+    // 修复3：body 可能已被 Whistle 预解析为对象，直接提取而非走 JSON.parse
+    if (typeof body === 'object' && body !== null) {
+      return extractFlatParams(body)
+    }
+
+    if (typeof body !== 'string' || !body.trim()) {
+      return {}
+    }
+
+    const parsed = JSON.parse(body)
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return {}
+    }
+
+    return extractFlatParams(parsed)
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 从对象中提取第一层 string/number/boolean 类型的 key-value（统一转为字符串）
+ * @param {Object} obj
+ * @returns {Object}
+ */
+function extractFlatParams(obj) {
+  const params = {}
+  Object.keys(obj).forEach((key) => {
+    const val = obj[key]
+    if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+      params[key] = String(val)
+    }
+  })
+  return params
+}
+
 /**
  * 检查是否需要捕获源数据
  * 如果文件已存在配置，则透传；如果是首次访问，则需要捕获
@@ -99,6 +288,7 @@ async function handleConcurrentCapture(capturingFiles, captureKey, params) {
     filename,
     mockVersion,
     filePath,
+    originalReq,
   } = params
 
   if (!capturingFiles.has(captureKey)) {
@@ -125,6 +315,7 @@ async function handleConcurrentCapture(capturingFiles, captureKey, params) {
         groupManager,
         currentGroupId,
         filename,
+        originalReq,
       })
 
       return { handled: true, response: 'success' }

package/lib/core/server-entry/server.js

@@ -16,7 +16,6 @@ const {
 } = require('./request-interceptor')
 const {
   sendMockResponse,
-  checkShouldCapture,
   handleConcurrentCapture,
 } = require('./response-handler')
 const {
@@ -69,6 +68,10 @@ module.exports = (server, options) => {
       return req.passThrough()
     }
 
+    // 在所有 await 操作之前提前捕获 originalReq
+    // Whistle 在异步操作完成后可能会清空 req.originalReq，导致后续读取为 null
+    const originalReq = req.originalReq
+
     // 提取请求信息
     const { filename, rule, method, url, pattern, ruleValue, mode } = interceptResult
 
@@ -98,12 +101,15 @@ module.exports = (server, options) => {
 
         // 有 mock 且有数据 → 返回 mock（不捕获）
         console.log(`[mockbubu] ✅ Mock-Only 模式: 返回 Mock 数据（不捕获） | URL: ${url}`)
-        return await sendMockResponse(res, sourceData, {
+        const mockOnlyResult = await sendMockResponse(res, sourceData, {
           mockVersion,
           groupManager,
           currentGroupId,
           filename,
+          originalReq,
         })
+        if (mockOnlyResult?.action === 'passthrough') return req.passThrough()
+        return
       }
 
       // 以下是 Capture 模式的逻辑
@@ -111,32 +117,23 @@ module.exports = (server, options) => {
 
       // 场景 1: Mock 启用 + 有源数据 → 返回 Mock 数据
       if (mock && sourceData) {
-        return await sendMockResponse(res, sourceData, {
+        const mockResult = await sendMockResponse(res, sourceData, {
           mockVersion,
           groupManager,
           currentGroupId,
           filename,
+          originalReq,
         })
+        if (mockResult?.action === 'passthrough') return req.passThrough()
+        return
       }
 
       // 场景 2: Mock 启用 + 无源数据 → 容错恢复（自动捕获源数据）
       // 可能原因：文件被删除、索引损坏、组导入不完整等
+      // sourceData=null 已证明物理文件无有效数据，不再通过索引判断是否跳过（索引残留会误阻恢复捕获）
       if (mock && !sourceData) {
         const captureKey = `${currentGroupId}/${filename}`
 
-        // 检查文件是否已存在
-        const { shouldCapture, isFirstCapture } = await checkShouldCapture({
-          storageAdapter,
-          groupManager,
-          currentGroupId,
-          filename,
-        })
-
-        if (!shouldCapture) {
-          // 文件已存在，直接透传
-          return req.passThrough()
-        }
-
         // 处理并发捕获
         const concurrentResult = await handleConcurrentCapture(capturingFiles, captureKey, {
           res,
@@ -146,6 +143,7 @@ module.exports = (server, options) => {
           filename,
           mockVersion,
           filePath,
+          originalReq,
         })
 
         if (concurrentResult.handled) {
@@ -164,7 +162,7 @@ module.exports = (server, options) => {
           memoryBuffer,
           currentGroupId,
           filename,
-          isFirstCapture,
+          isFirstCapture: true,
           mock: true, // mock 状态
           requestInfo: { method, rule, pattern, ruleValue, url },
           capturingFiles,
@@ -179,23 +177,10 @@ module.exports = (server, options) => {
           return req.passThrough()
         }
 
-        // 3.2: 无源数据 → 检查是否需要捕获
+        // 3.2: 无源数据 → 捕获
+        // sourceData=null 已证明物理文件无有效数据，不再通过索引判断是否跳过（索引残留会误阻捕获）
         const captureKey = `${currentGroupId}/${filename}`
 
-        // 检查文件是否已存在
-        const { shouldCapture, isFirstCapture } = await checkShouldCapture({
-          storageAdapter,
-          groupManager,
-          currentGroupId,
-          filename,
-        })
-
-        if (!shouldCapture) {
-          // 文件已存在，直接透传
-          console.log(`[mockbubu] ⏭️  文件已存在（mock=false），跳过捕获并透传: ${filename}`)
-          return req.passThrough()
-        }
-
         // 检查是否正在捕获中
         if (capturingFiles.has(captureKey)) {
           // mock=false 时，并发请求直接透传（不等待）
@@ -212,7 +197,7 @@ module.exports = (server, options) => {
           memoryBuffer,
           currentGroupId,
           filename,
-          isFirstCapture,
+          isFirstCapture: true,
           mock: false, // mock 状态
           requestInfo: { method, rule, pattern, ruleValue, url },
           capturingFiles,

package/lib/storage/group-manager.js

@@ -486,6 +486,83 @@ class GroupManager {
     }
   }
 
+  // ========================================
+  // 条件匹配规则（match_versions）业务封装
+  // ========================================
+
+  /**
+   * 通过 filename（URL）查找 fileId 的通用内部方法
+   * @private
+   */
+  async _getFileIdByFilename(groupId, filename) {
+    const v3Storage = this.storage.getV3Storage()
+    v3Storage.invalidateIndex(groupId)
+    const index = await v3Storage.getIndex(groupId)
+    const fileEntry = index.files.find(f => f.url === filename)
+    if (!fileEntry) {
+      throw new Error(`文件不存在: ${filename}`)
+    }
+    return fileEntry.id
+  }
+
+  /**
+   * 获取文件的所有匹配规则列表
+   * @param {string} groupId - 组ID
+   * @param {string} filename - 文件URL
+   * @returns {Promise<Array>} 匹配规则列表
+   */
+  async getMatchVersions(groupId, filename) {
+    const v3Storage = this.storage.getV3Storage()
+    try {
+      const fileId = await this._getFileIdByFilename(groupId, filename)
+      return await v3Storage.listMatchVersions(groupId, fileId)
+    } catch (err) {
+      this.logger.error('获取匹配规则列表失败:', err.message)
+      return []
+    }
+  }
+
+  /**
+   * 创建匹配规则
+   * @param {string} groupId - 组ID
+   * @param {string} filename - 文件URL
+   * @param {Object} data - 规则数据
+   */
+  async createMatchVersion(groupId, filename, data) {
+    const v3Storage = this.storage.getV3Storage()
+    const fileId = await this._getFileIdByFilename(groupId, filename)
+    return await v3Storage.createMatchVersion(groupId, fileId, data)
+  }
+
+  /**
+   * 更新匹配规则
+   * @param {string} groupId - 组ID
+   * @param {string} filename - 文件URL
+   * @param {string} matchVersionId - 规则ID
+   * @param {Object} updates - 要更新的字段
+   */
+  async updateMatchVersion(groupId, filename, matchVersionId, updates) {
+    const v3Storage = this.storage.getV3Storage()
+    const fileId = await this._getFileIdByFilename(groupId, filename)
+    return await v3Storage.updateMatchVersion(groupId, fileId, matchVersionId, updates)
+  }
+
+  /**
+   * 删除匹配规则
+   * @param {string} groupId - 组ID
+   * @param {string} filename - 文件URL
+   * @param {string} matchVersionId - 规则ID
+   */
+  async deleteMatchVersion(groupId, filename, matchVersionId) {
+    const v3Storage = this.storage.getV3Storage()
+    const fileId = await this._getFileIdByFilename(groupId, filename)
+    return await v3Storage.deleteMatchVersion(groupId, fileId, matchVersionId)
+  }
+
+  // ========================================
+  // URL/Payload 工具方法
+  // ========================================
+
   /**
    * 从 URL 提取 query 参数
    * @param {string} url - 完整的 URL

package/lib/storage/storage-v3.js

@@ -656,6 +656,7 @@ class FileSystemStorage {
       rule: fileData.rule || '',
       ruleValue: fileData.ruleValue || '',
       pattern: fileData.pattern || '',
+      remark: fileData.remark || '',
       config,
       session: fileData.session || null, // ✅ 保存完整 session 数据
       createTime: Date.now(),
@@ -677,6 +678,7 @@ class FileSystemStorage {
       mock: config.mock,
       locked: config.locked,
       mockVersion: config.mockVersion,
+      remark: fileData.remark || '',
       versionCount: 0,
       createTime: file.createTime,
       updateTime: file.updateTime,
@@ -779,6 +781,7 @@ class FileSystemStorage {
       mock: updated.config?.mock,
       locked: updated.config?.locked,
       mockVersion: updated.config?.mockVersion,
+      ...(updated.remark !== undefined && { remark: updated.remark }),
       updateTime: updated.updateTime,
       // ✨ Phase 3.1: 索引增强字段
       ...(updated.url && {
@@ -1134,6 +1137,163 @@ class FileSystemStorage {
     })
   }
 
+  // ========================================
+  // 条件匹配规则（match_versions）
+  // ========================================
+
+  /**
+   * 获取 match_versions 目录路径
+   * @param {string} groupId - 组ID
+   * @param {string} fileId - 文件ID
+   * @returns {string} 目录路径
+   */
+  getMatchVersionsDir(groupId, fileId) {
+    return path.join(this.groupsDir, groupId, 'files', fileId, 'match_versions')
+  }
+
+  /**
+   * 获取匹配规则数量
+   */
+  async getMatchVersionCount(groupId, fileId) {
+    const matchVersionsDir = this.getMatchVersionsDir(groupId, fileId)
+    try {
+      const entries = await fs.readdir(matchVersionsDir)
+      return entries.filter(e => e.endsWith('.json')).length
+    } catch (err) {
+      if (err.code === 'ENOENT') return 0
+      throw err
+    }
+  }
+
+  /**
+   * 获取所有匹配规则列表
+   */
+  async listMatchVersions(groupId, fileId) {
+    const matchVersionsDir = this.getMatchVersionsDir(groupId, fileId)
+
+    try {
+      const entries = await fs.readdir(matchVersionsDir)
+      const matchVersions = []
+
+      for (const entry of entries) {
+        if (entry.endsWith('.json')) {
+          const matchVersionId = entry.replace('.json', '')
+          const data = await this.getMatchVersionById(groupId, fileId, matchVersionId)
+          if (data) {
+            matchVersions.push(data)
+          }
+        }
+      }
+
+      // 按 priority 升序排序（数字越小越靠前），priority 相同按 createTime 升序
+      matchVersions.sort((a, b) => {
+        const priorityDiff = (a.priority || 0) - (b.priority || 0)
+        if (priorityDiff !== 0) return priorityDiff
+        return (a.createTime || 0) - (b.createTime || 0)
+      })
+
+      return matchVersions
+    } catch (err) {
+      if (err.code === 'ENOENT') return []
+      throw err
+    }
+  }
+
+  /**
+   * 通过ID获取单个匹配规则
+   */
+  async getMatchVersionById(groupId, fileId, matchVersionId) {
+    const matchVersionFile = path.join(
+      this.getMatchVersionsDir(groupId, fileId),
+      `${matchVersionId}.json`,
+    )
+    try {
+      const content = await fs.readFile(matchVersionFile, 'utf8')
+      return JSON.parse(content)
+    } catch (err) {
+      if (err.code === 'ENOENT') return null
+      throw err
+    }
+  }
+
+  /**
+   * 创建匹配规则
+   * @param {string} groupId - 组ID
+   * @param {string} fileId - 文件ID
+   * @param {Object} matchVersionData - 规则数据 { name, description?, conditions?, content?, priority? }
+   */
+  async createMatchVersion(groupId, fileId, matchVersionData) {
+    const matchVersionsDir = this.getMatchVersionsDir(groupId, fileId)
+    await fs.mkdir(matchVersionsDir, { recursive: true })
+
+    // 生成唯一ID，前缀 mv_
+    const matchVersionId = 'mv_' + this.generateFileId()
+
+    const matchVersion = {
+      id: matchVersionId,
+      name: matchVersionData.name || '默认',
+      description: matchVersionData.description || '',
+      conditions: matchVersionData.conditions || [],
+      content: matchVersionData.content || {},
+      priority: matchVersionData.priority || 0,
+      createTime: Date.now(),
+      updateTime: Date.now(),
+    }
+
+    const matchVersionFile = path.join(matchVersionsDir, `${matchVersionId}.json`)
+    await this._writeJSON(matchVersionFile, matchVersion)
+
+    // 同步更新索引中的 matchVersionCount
+    const count = await this.getMatchVersionCount(groupId, fileId)
+    await this._updateInIndex(groupId, fileId, { matchVersionCount: count })
+
+    return matchVersion
+  }
+
+  /**
+   * 更新匹配规则（通过ID）
+   * @param {string} groupId - 组ID
+   * @param {string} fileId - 文件ID
+   * @param {string} matchVersionId - 规则ID
+   * @param {Object} updates - 要更新的字段 { name?, description?, conditions?, content?, priority? }
+   */
+  async updateMatchVersion(groupId, fileId, matchVersionId, updates) {
+    const existing = await this.getMatchVersionById(groupId, fileId, matchVersionId)
+    if (!existing) {
+      throw new Error(`匹配规则不存在: ${matchVersionId}`)
+    }
+
+    const updated = {
+      ...existing,
+      ...updates,
+      id: matchVersionId, // 确保ID不被修改
+      updateTime: Date.now(),
+    }
+
+    const matchVersionFile = path.join(
+      this.getMatchVersionsDir(groupId, fileId),
+      `${matchVersionId}.json`,
+    )
+    await this._writeJSON(matchVersionFile, updated)
+
+    return updated
+  }
+
+  /**
+   * 删除匹配规则（通过ID）
+   */
+  async deleteMatchVersion(groupId, fileId, matchVersionId) {
+    const matchVersionFile = path.join(
+      this.getMatchVersionsDir(groupId, fileId),
+      `${matchVersionId}.json`,
+    )
+    await fs.unlink(matchVersionFile)
+
+    // 同步更新索引中的 matchVersionCount
+    const count = await this.getMatchVersionCount(groupId, fileId)
+    await this._updateInIndex(groupId, fileId, { matchVersionCount: count })
+  }
+
   // ========================================
   // 内部辅助方法
   // ========================================

package/lib/uiServer/router/files/api-list-router.js

@@ -49,8 +49,7 @@ module.exports = (router) => {
    *       method: 'GET',
    *       status: 200,
    *       mock: true,
-   *       locked: false,
-   *       session: {...}  // 完整会话数据
+   *       locked: false
    *     }
    *   ],
    *   msg: '操作成功'