whistle.mockbubu 2.0.0 → 2.1.0

package/lib/utils/utils.js

@@ -0,0 +1,541 @@
+/**
+ * 文件名: utils.js
+ * 功能: Whistle.mockbubu 工具函数集
+ * 依赖: logger.js, const.js, path-utils.js
+ * 更新: 2025-12-02
+ *
+ * 职责:
+ * - 文件操作函数（读取、更新、列表查询）
+ * - URL 和请求处理（文件名生成、规则构造）
+ * - 响应数据处理（解压缩、类型转换）
+ * - API 列表更新标志管理
+ *
+ * 架构特点:
+ * - V3 架构简化版本，移除废弃的版本管理函数
+ * - 使用 StorageAdapter 适配层，屏蔽底层存储细节
+ * - 支持多种压缩格式（gzip、deflate、brotli）
+ *
+ * 使用示例:
+ * ```javascript
+ * const { getFilename, readSession } = require('./utils')
+ *
+ * // 获取文件名
+ * const filename = getFilename(originalReq)
+ *
+ * // 读取 session 数据
+ * const session = await readSession(storage, filename, groupId)
+ * ```
+ */
+
+const zlib = require('zlib')
+const { createLogger } = require('./logger')
+const { RuleValueMap, SystemConstants } = require('../config/const')
+const { buildPath } = require('./path-utils')
+
+// 创建 logger 实例
+const logger = createLogger('utils')
+
+// ========================================
+// 文件操作函数
+// ========================================
+
+/**
+ * 按组获取文件列表
+ * 从所有文件中过滤出属于指定组的文件
+ *
+ * 工作流程:
+ * 1. 调用 storage.getFileList() 获取所有文件
+ * 2. 过滤出以 "{groupId}/" 开头的文件
+ * 3. 去除路径前缀，返回纯文件名列表
+ *
+ * 文件名格式:
+ * - 输入（storage）：groupId/filename（例如：default/https://api.test.com/users）
+ * - 输出：filename（例如：https://api.test.com/users）
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @param {string} groupId - 组ID
+ * @returns {Promise<Array>} 文件列表，每个文件包含 name 和 size
+ *
+ * @example
+ * const files = await getGroupFileList(storage, 'default')
+ * files.forEach(file => {
+ *   console.log(file.name, file.size)
+ * })
+ * // 输出示例:
+ * // https://api.test.com/users 1024
+ * // https://api.test.com/posts 2048
+ */
+const getGroupFileList = async (storage, groupId) => {
+  // 参数校验
+  if (!groupId) {
+    logger.warn('getGroupFileList: groupId 为空，返回空数组')
+    return []
+  }
+
+  try {
+    // 1. 获取所有文件列表
+    // StorageAdapter 返回的格式: groupId/filename（不需要解码）
+    const allFiles = await storage.getFileList() || []
+    const groupPrefix = `${groupId}/`
+    const result = []
+
+    // 2. 过滤出属于该组的文件
+    allFiles.forEach((item) => {
+      try {
+        // StorageAdapter 返回的文件名格式: groupId/filename
+        // 例如: default/https://m.shein.com/us/bff-api/...
+        // 不需要任何解码，直接使用
+        const name = item.name
+
+        // 检查是否以 "groupId/" 开头
+        if (name.startsWith(groupPrefix)) {
+          // 3. 提取纯文件名（去除 groupId/ 前缀）
+          const filename = name.substring(groupPrefix.length)
+
+          result.push({
+            name: filename, // 返回纯文件名，不包含 groupId 前缀
+            size: item.size || 0, // 文件大小（字节）
+          })
+        }
+      } catch (err) {
+        // 处理失败时跳过该文件，不中断整体流程
+        logger.warn(`处理文件失败: ${item.name}`, err.message)
+      }
+    })
+
+    return result
+  } catch (error) {
+    logger.error('getGroupFileList 执行失败:', error.message)
+
+    // 仅在开发环境输出堆栈
+    if (process.env.NODE_ENV === 'development') {
+      logger.error('错误堆栈:', error.stack)
+    }
+
+    return [] // 失败时返回空数组，避免中断业务
+  }
+}
+
+/**
+ * 更新文件的响应体
+ * 读取现有 session，更新 res.body 字段，然后保存
+ *
+ * 注意:
+ * - 仅更新响应体，不修改其他字段
+ * - 如果文件不存在，不会创建新文件
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @param {string} filename - 文件名（URL）
+ * @param {Object} body - 新的响应体内容（会被 JSON.stringify）
+ * @param {string} groupId - 组ID
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await updateFile(storage, 'https://api.test.com/users', { data: [...] }, 'default')
+ */
+const updateFile = async (storage, filename, body, groupId) => {
+  if (!filename) {
+    throw new Error('文件名不能为空')
+  }
+
+  // 构造文件路径：groupId/filename
+  const filePath = groupId ? buildPath(groupId, filename) : filename
+
+  // 读取现有 session 数据
+  const sourceDataStr = await storage.readFile(filePath)
+  if (sourceDataStr) {
+    const session = JSON.parse(sourceDataStr)
+    // 更新响应体（JSON 序列化）
+    session.res.body = JSON.stringify(body)
+    // 保存更新后的 session 数据
+    await storage.writeFile(filePath, JSON.stringify(session))
+  }
+}
+
+/**
+ * 读取文件的响应体
+ * 仅返回 res.body 字段，不返回完整 session
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @param {string} filename - 文件名（URL）
+ * @param {string} groupId - 组ID
+ * @returns {Promise<string|undefined>} 响应体内容，文件不存在返回 undefined
+ *
+ * @example
+ * const body = await readFile(storage, 'https://api.test.com/users', 'default')
+ * console.log(body) // '{"data": [...]}'
+ */
+const readFile = async (storage, filename, groupId) => {
+  // 构造文件路径：groupId/filename
+  const filePath = groupId ? buildPath(groupId, filename) : filename
+
+  // 读取源数据 (storageAdapter.readFile 返回的是 session 对象的 JSON 字符串)
+  const sourceDataStr = await storage.readFile(filePath)
+  if (sourceDataStr) {
+    try {
+      // 解析后得到 session 对象 {req, res, ...}
+      const session = JSON.parse(sourceDataStr)
+      return session?.res?.body
+    } catch (err) {
+      console.error('[mockbubu] readFile parse error:', err.message)
+      return undefined
+    }
+  }
+}
+
+/**
+ * 读取完整的 session 数据（包含 req 和 res）
+ * 返回完整的 session 对象，包括请求和响应信息
+ *
+ * Session 结构:
+ * ```javascript
+ * {
+ *   req: {
+ *     method: 'GET',
+ *     url: 'https://api.test.com/users',
+ *     headers: {...},
+ *     body: '...'
+ *   },
+ *   res: {
+ *     statusCode: 200,
+ *     headers: {...},
+ *     body: '{"data": [...]}'
+ *   }
+ * }
+ * ```
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @param {string} filename - 文件名（URL）
+ * @param {string} groupId - 组ID
+ * @returns {Promise<Object|null>} session 对象，文件不存在返回 null
+ *
+ * @example
+ * const session = await readSession(storage, 'https://api.test.com/users', 'default')
+ * if (session) {
+ *   console.log('请求方法:', session.req.method)
+ *   console.log('响应状态:', session.res.statusCode)
+ *   console.log('响应内容:', session.res.body)
+ * }
+ */
+const readSession = async (storage, filename, groupId) => {
+  // 构造文件路径：groupId/filename
+  const filePath = groupId ? buildPath(groupId, filename) : filename
+
+  // 读取源数据 (storageAdapter.readFile 返回的就是 session 对象的 JSON 字符串)
+  const sourceDataStr = await storage.readFile(filePath)
+  if (sourceDataStr) {
+    return JSON.parse(sourceDataStr)
+  }
+  return null
+}
+
+// ========================================
+// URL 和请求处理函数
+// ========================================
+
+/**
+ * 获取 Mock 文件名
+ * 根据 Whistle 规则类型（ruleValue）从 URL 生成文件名
+ *
+ * 规则类型:
+ * - **href**: 完整 URL（包含 query 参数）
+ * - **pathname**: origin + pathname（默认，不含 query）
+ * - **pattern**: 使用 Whistle pattern 作为文件名
+ *
+ * 示例:
+ * - href: `https://api.test.com/users?id=1`
+ * - pathname: `https://api.test.com/users`
+ * - pattern: `*.test.com`
+ *
+ * @param {Object} originalReq - Whistle 原始请求对象
+ * @param {string} originalReq.url - 完整 URL
+ * @param {string} originalReq.ruleValue - 规则类型（href/pathname/pattern）
+ * @param {string} originalReq.pattern - Whistle pattern（仅 pattern 模式使用）
+ * @returns {string} 文件名
+ *
+ * @example
+ * const req = {
+ *   url: 'https://api.test.com/users?id=1',
+ *   ruleValue: 'pathname',
+ *   pattern: '*.test.com'
+ * }
+ * const filename = getFilename(req)
+ * console.log(filename) // 'https://api.test.com/users'
+ */
+const getFilename = (originalReq) => {
+  const { url, ruleValue, pattern } = originalReq
+  const u = new URL(url)
+  let filename = url
+
+  // 根据规则类型生成文件名
+  switch (ruleValue) {
+  case RuleValueMap.href:
+    // 完整 URL（包含 query 参数）
+    filename = u.href
+    break
+  case RuleValueMap.pathname:
+    // origin + pathname（不含 query）
+    filename = u.origin + u.pathname
+    break
+  case RuleValueMap.pattern:
+    // 使用 Whistle pattern 作为文件名
+    filename = pattern
+    break
+  default:
+    // 默认使用 pathname 模式
+    filename = u.origin + u.pathname
+  }
+
+  return filename
+}
+
+/**
+ * 获取 API 列表更新标志
+ * 检查是否有新的 API 被捕获（需要刷新列表）
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @returns {Promise<boolean>} true 表示有更新，false 表示无更新
+ *
+ * @example
+ * const updated = await getApiListUpdated(storage)
+ * if (updated) {
+ *   console.log('API 列表有更新，需要刷新')
+ * }
+ */
+const getApiListUpdated = async (storage) => {
+  const value = await storage.getProperty(SystemConstants.API_LIST_UPDATED_KEY)
+  return !!value
+}
+
+/**
+ * 设置 API 列表更新标志
+ * 当有新的 API 被捕获时，设置此标志为 true
+ *
+ * @param {StorageAdapter} storage - 存储适配器实例
+ * @param {boolean} updated - 是否有更新
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await setApiListUpdated(storage, true)
+ */
+const setApiListUpdated = async (storage, updated) => {
+  return await storage.setProperty(SystemConstants.API_LIST_UPDATED_KEY, updated)
+}
+
+/**
+ * 获取 Whistle 规则字符串
+ * 根据 pattern 和 ruleValue 构造完整的规则
+ *
+ * @param {Object} originalReq - Whistle 原始请求对象
+ * @param {string} originalReq.pattern - Whistle pattern
+ * @param {string} originalReq.ruleValue - 规则类型
+ * @returns {string} 规则字符串
+ *
+ * @example
+ * const req = { pattern: '*.test.com', ruleValue: 'pathname' }
+ * const rule = getRule(req)
+ * console.log(rule) // '*.test.com mockbubu://pathname'
+ */
+const getRule = (originalReq) => {
+  const { pattern, ruleValue } = originalReq
+  return `${pattern} mockbubu://${ruleValue}`
+}
+
+/**
+ * 判断是否为 JSON 请求
+ * 通过请求头判断请求是否期望 JSON 响应
+ *
+ * 判断依据:
+ * 1. `Accept` 头包含 `application/json`
+ * 2. `sec-fetch-dest` 或 `Sec-Fetch-Dest` 为 `empty`
+ *
+ * 注意:
+ * - `sec-fetch-dest: empty` 通常表示 fetch/XHR 请求
+ * - 用于决定是否捕获并 mock 该请求
+ *
+ * @param {Object} headers - 请求头对象
+ * @param {string} headers.accept - Accept 头
+ * @param {string} headers['sec-fetch-dest'] - Fetch Destination（小写）
+ * @param {string} headers['Sec-Fetch-Dest'] - Fetch Destination（大写）
+ * @returns {boolean} true 表示是 JSON 请求
+ *
+ * @example
+ * const headers = {
+ *   accept: 'application/json',
+ *   'sec-fetch-dest': 'empty'
+ * }
+ * const isJson = isJsonReq(headers)
+ * console.log(isJson) // true
+ */
+const isJsonReq = (headers) => {
+  const result = (
+    (headers.accept && headers.accept.includes('application/json')) ||
+    headers['sec-fetch-dest'] === 'empty' ||
+    headers['Sec-Fetch-Dest'] === 'empty'
+  )
+
+  // 调试日志（仅用于特定域名）
+  // 可通过环境变量或配置开关控制
+  if (process.env.DEBUG_HOST && headers.host === process.env.DEBUG_HOST) {
+    const fullUrl = headers['x-whistle-full-url'] || 'unknown'
+    logger.log(`[isJsonReq] ${headers.host} 请求: ${decodeURIComponent(fullUrl)}`)
+    logger.log('  - Accept:', headers.accept)
+    logger.log('  - sec-fetch-dest:', headers['sec-fetch-dest'])
+    logger.log('  - Sec-Fetch-Dest:', headers['Sec-Fetch-Dest'])
+    logger.log('  - 判断结果:', result)
+  }
+
+  return result
+}
+
+// ========================================
+// 工具函数
+// ========================================
+
+/**
+ * 为异步函数添加 try-catch 包装
+ * 捕获异常并在开发环境输出日志，然后重新抛出
+ *
+ * 使用场景:
+ * - 包装可能抛出异常的函数
+ * - 在开发环境提供更好的错误日志
+ * - 不改变原函数的返回值和异常行为
+ *
+ * 注意:
+ * - 异常仍会被抛出，只是在抛出前记录日志
+ * - 仅在开发环境输出日志，生产环境静默
+ *
+ * @param {Function} fn - 要包装的异步函数
+ * @returns {Function} 包装后的函数
+ *
+ * @example
+ * const safeReadFile = withTryCatch(async (filename) => {
+ *   return await fs.readFile(filename, 'utf-8')
+ * })
+ *
+ * try {
+ *   const content = await safeReadFile('test.json')
+ * } catch (err) {
+ *   // 开发环境会先输出日志，再抛出异常
+ *   console.error('读取失败:', err)
+ * }
+ */
+const withTryCatch = (fn) => {
+  return async (...args) => {
+    try {
+      return await fn(...args)
+    } catch (e) {
+      // 仅在开发环境输出错误日志
+      if (process.env.NODE_ENV === 'development') {
+        logger.error('全局捕获异常:', e)
+      }
+      // 重新抛出异常，不改变原函数行为
+      throw e
+    }
+  }
+}
+
+// ========================================
+// 导出 - V3 架构使用的函数
+// ========================================
+
+// 文件操作
+exports.getGroupFileList = getGroupFileList
+exports.updateFile = updateFile
+exports.readFile = readFile
+exports.readSession = readSession
+
+// URL 和请求处理
+exports.getFilename = getFilename
+exports.getRule = getRule
+exports.isJsonReq = isJsonReq
+
+// API 列表更新标志
+exports.getApiListUpdated = getApiListUpdated
+exports.setApiListUpdated = setApiListUpdated
+
+// 工具函数
+exports.withTryCatch = withTryCatch
+
+/**
+ * 将响应 Buffer 解压并转换为字符串
+ * 支持多种压缩格式和数据类型
+ *
+ * 支持的压缩格式:
+ * - **gzip**: 使用 zlib.gunzipSync() 解压
+ * - **deflate**: 使用 zlib.inflateSync() 解压
+ * - **br** (brotli): 使用 zlib.brotliDecompressSync() 解压
+ *
+ * 支持的数据类型:
+ * - **String**: 直接返回
+ * - **Object**: JSON.stringify() 序列化
+ * - **Uint8Array**: toString() 转换
+ * - **其他**: 原样返回
+ *
+ * 工作流程:
+ * 1. 根据 encoding 解压缩 body
+ * 2. 根据数据类型转换为字符串
+ * 3. 返回字符串内容
+ *
+ * @param {Object} params - 参数对象
+ * @param {Buffer|string|Object|Uint8Array} params.body - 响应体数据
+ * @param {string} params.encoding - 压缩编码类型（gzip/deflate/br）
+ * @returns {string} 转换后的字符串内容
+ *
+ * @example
+ * // 解压 gzip 数据
+ * const result = handleBuffer2String({
+ *   body: gzipBuffer,
+ *   encoding: 'gzip'
+ * })
+ * console.log(result) // '{"data": [...]}'
+ *
+ * @example
+ * // 处理 JSON 对象
+ * const result = handleBuffer2String({
+ *   body: { data: [1, 2, 3] },
+ *   encoding: undefined
+ * })
+ * console.log(result) // '{"data":[1,2,3]}'
+ */
+exports.handleBuffer2String = withTryCatch(({ body, encoding }) => {
+  // 1. 根据编码类型解压缩
+  switch (encoding) {
+  case 'gzip':
+    body = zlib.gunzipSync(body)
+    break
+  case 'deflate':
+    body = zlib.inflateSync(body)
+    break
+  case 'br':
+    body = zlib.brotliDecompressSync(body)
+    break
+  default:
+    // 无压缩或未知编码，保持原样
+    break
+  }
+
+  // 2. 根据数据类型转换为字符串
+  const type = Object.prototype.toString.call(body)
+  let content
+
+  switch (type) {
+  case '[object String]':
+    // 已经是字符串，直接返回
+    content = body
+    break
+  case '[object Object]':
+    // 对象类型，JSON 序列化
+    content = JSON.stringify(body)
+    break
+  case '[object Uint8Array]':
+    // Uint8Array 类型，转换为字符串
+    content = body.toString()
+    break
+  default:
+    // 其他类型，原样返回
+    content = body
+  }
+
+  return content
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whistle.mockbubu",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "mock response data",
   "scripts": {
     "lint": "eslint . --ext .js",
@@ -25,7 +25,7 @@
     ".gitignore",
     "index.js",
     "package.json",
-    "*.md",
+    "README.md",
     "step1.png",
     "step2.png"
   ],