whistle.mockbubu 2.0.0 → 2.1.1

package/lib/utils/error-handler.js

@@ -0,0 +1,173 @@
+/**
+ * 文件名: error-handler.js
+ * 功能: 统一的错误处理工具
+ * 依赖: logger.js
+ * 更新: 2025-12-02
+ *
+ * 使用示例:
+ * ```javascript
+ * const { withErrorHandling, createErrorResponse } = require('./error-handler')
+ *
+ * // 包装异步函数
+ * const safeReadFile = withErrorHandling(
+ *   readFile,
+ *   { operationName: '读取文件', rethrow: false }
+ * )
+ *
+ * // 创建错误响应
+ * ctx.body = createErrorResponse('文件不存在', 404)
+ * ```
+ *
+ * 注意事项:
+ * - 错误会自动记录到日志
+ * - 可以选择是否重新抛出异常
+ * - 支持自定义错误处理回调
+ */
+
+const { createLogger } = require('./logger')
+
+/**
+ * 包装异步函数,添加统一错误处理
+ *
+ * 自动记录错误日志,可选择是否重新抛出异常
+ *
+ * @param {Function} fn - 要包装的异步函数
+ * @param {Object} options - 配置选项
+ * @param {string} options.operationName - 操作名称 (用于日志)
+ * @param {boolean} options.rethrow - 是否重新抛出异常 (默认: true)
+ * @param {Function} options.onError - 自定义错误处理函数
+ * @param {*} options.defaultReturn - 捕获异常后的默认返回值 (默认: null)
+ * @returns {Function} 包装后的函数
+ *
+ * @example
+ * // 包装函数,捕获异常但不抛出
+ * const safeReadFile = withErrorHandling(
+ *   readFile,
+ *   { operationName: '读取文件', rethrow: false }
+ * )
+ *
+ * const content = await safeReadFile('test.json')
+ * // 如果读取失败,返回 null 而不是抛出异常
+ *
+ * @example
+ * // 包装函数,自定义错误处理
+ * const safeWriteFile = withErrorHandling(
+ *   writeFile,
+ *   {
+ *     operationName: '写入文件',
+ *     onError: (err, args) => {
+ *       console.log('写入失败的文件:', args[0])
+ *     }
+ *   }
+ * )
+ */
+function withErrorHandling(fn, options = {}) {
+  const {
+    operationName = '操作',
+    rethrow = true,
+    onError = null,
+    defaultReturn = null,
+  } = options
+
+  return async function (...args) {
+    const logger = createLogger()
+    try {
+      return await fn.apply(this, args)
+    } catch (err) {
+      // 记录错误日志
+      logger.error(`${operationName}失败:`, err.message)
+
+      // 仅在开发环境输出完整堆栈
+      if (process.env.NODE_ENV === 'development') {
+        logger.error('错误堆栈:', err.stack)
+      }
+
+      // 调用自定义错误处理函数
+      if (onError) {
+        try {
+          onError(err, args)
+        } catch (callbackErr) {
+          logger.error('错误处理回调执行失败:', callbackErr.message)
+        }
+      }
+
+      // 是否重新抛出异常
+      if (rethrow) {
+        throw err
+      }
+
+      return defaultReturn
+    }
+  }
+}
+
+/**
+ * 创建错误响应对象 (用于HTTP响应)
+ *
+ * @param {string} message - 错误消息
+ * @param {number} code - 错误代码 (默认: 500)
+ * @param {Object} details - 详细信息 (可选)
+ * @returns {Object} 错误响应对象
+ *
+ * @example
+ * createErrorResponse('文件不存在', 404)
+ * // => { code: 404, msg: '文件不存在' }
+ *
+ * createErrorResponse('参数验证失败', 400, { errors: [...] })
+ * // => { code: 400, msg: '参数验证失败', data: { errors: [...] } }
+ */
+function createErrorResponse(message, code = 500, details = null) {
+  return {
+    code,
+    msg: message || '操作失败',
+    ...(details && { data: details }),
+  }
+}
+
+/**
+ * 创建成功响应对象 (用于HTTP响应)
+ *
+ * @param {*} data - 响应数据
+ * @param {string} message - 成功消息 (默认: '操作成功')
+ * @returns {Object} 成功响应对象
+ *
+ * @example
+ * createSuccessResponse({ id: 123 })
+ * // => { code: 200, msg: '操作成功', data: { id: 123 } }
+ *
+ * createSuccessResponse(null, '删除成功')
+ * // => { code: 200, msg: '删除成功' }
+ */
+function createSuccessResponse(data = null, message = '操作成功') {
+  return {
+    code: 200,
+    msg: message,
+    ...(data !== null && data !== undefined && { data }),
+  }
+}
+
+/**
+ * 安全执行异步函数 (简化版的 withErrorHandling)
+ *
+ * @param {Function} fn - 要执行的异步函数
+ * @param {string} operationName - 操作名称
+ * @returns {Promise<*>} 执行结果,失败时返回 null
+ *
+ * @example
+ * const data = await safeExecute(
+ *   () => storage.readFile('test.json'),
+ *   '读取文件'
+ * )
+ * // 失败时返回 null,不抛出异常
+ */
+async function safeExecute(fn, operationName = '操作') {
+  const wrapped = withErrorHandling(fn, { operationName, rethrow: false })
+  return await wrapped()
+}
+
+module.exports = {
+  withErrorHandling,
+  createErrorResponse,
+  createSuccessResponse,
+  safeExecute,
+}

package/lib/utils/logger.js

@@ -0,0 +1,79 @@
+/**
+ * 文件名: logger.js
+ * 功能: 统一的日志工具,提供带时间戳的日志输出
+ * 依赖: 无
+ * 更新: 2025-12-02
+ *
+ * 使用示例:
+ * ```javascript
+ * const { createLogger } = require('./logger')
+ * const logger = createLogger('myModule')
+ * logger.log('操作成功')
+ * logger.error('操作失败', error)
+ * ```
+ *
+ * 注意事项:
+ * - 时间格式统一为: YYYY/MM/DD HH:mm:ss
+ * - 日志前缀格式: [moduleName 时间戳]
+ */
+
+/**
+ * 格式化时间戳为中文格式
+ *
+ * @returns {string} 格式: "2025/12/02 15:30:45"
+ *
+ * @example
+ * formatTimestamp() // "2025/12/02 15:30:45"
+ */
+function formatTimestamp() {
+  const now = new Date()
+  const year = now.getFullYear()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const day = String(now.getDate()).padStart(2, '0')
+  const hours = String(now.getHours()).padStart(2, '0')
+  const minutes = String(now.getMinutes()).padStart(2, '0')
+  const seconds = String(now.getSeconds()).padStart(2, '0')
+  return `${year}/${month}/${day} ${hours}:${minutes}:${seconds}`
+}
+
+/**
+ * 创建带时间戳的日志工具
+ *
+ * 提供统一的日志输出格式: [prefix 时间戳] message
+ *
+ * @param {string} prefix - 日志前缀 (默认: "mockbubu")
+ * @returns {Object} 日志工具对象,包含 log, warn, error, info 方法
+ *
+ * @example
+ * const logger = createLogger('storage')
+ * logger.log('文件创建成功') // 输出: [storage 2025/12/02 15:30:45] 文件创建成功
+ * logger.error('文件创建失败:', error) // 输出: [storage 2025/12/02 15:30:45] 文件创建失败: Error: ...
+ */
+function createLogger(prefix = 'mockbubu') {
+  return {
+    /**
+     * 普通日志
+     */
+    log: (...args) => console.log(`[${prefix} ${formatTimestamp()}]`, ...args),
+
+    /**
+     * 警告日志
+     */
+    warn: (...args) => console.warn(`[${prefix} ${formatTimestamp()}]`, ...args),
+
+    /**
+     * 错误日志
+     */
+    error: (...args) => console.error(`[${prefix} ${formatTimestamp()}]`, ...args),
+
+    /**
+     * 信息日志
+     */
+    info: (...args) => console.info(`[${prefix} ${formatTimestamp()}]`, ...args),
+  }
+}
+
+module.exports = {
+  formatTimestamp,
+  createLogger,
+}

package/lib/utils/path-utils.js

@@ -0,0 +1,147 @@
+/**
+ * 文件名: path-utils.js
+ * 功能: 路径解析工具,处理 groupId/filename 格式的路径字符串
+ * 依赖: 无
+ * 更新: 2025-12-02
+ *
+ * 使用示例:
+ * ```javascript
+ * const { parsePath, parseConfigKey } = require('./path-utils')
+ *
+ * const { groupId, filename } = parsePath('default/https://api.test.com/users')
+ * console.log(groupId) // 'default'
+ * console.log(filename) // 'https://api.test.com/users'
+ * ```
+ *
+ * 注意事项:
+ * - 支持文件名中包含斜杠 (URL路径)
+ * - 配置键格式必须严格为 "group.{groupId}.file.{filename}"
+ */
+
+/**
+ * 解析完整路径为组ID和文件名
+ *
+ * 路径格式: "groupId/filename" 或 "filename"
+ * 当路径不包含斜杠时,使用默认组ID
+ *
+ * @param {string} pathStr - 完整路径字符串
+ * @param {string} defaultGroupId - 默认组ID (当路径不包含组时使用)
+ * @returns {{groupId: string, filename: string}} 解析结果
+ * @throws {Error} 路径为空时抛出异常
+ *
+ * @example
+ * parsePath('default/https://api.test.com/users')
+ * // => { groupId: 'default', filename: 'https://api.test.com/users' }
+ *
+ * parsePath('https://api.test.com/users', 'default')
+ * // => { groupId: 'default', filename: 'https://api.test.com/users' }
+ *
+ * parsePath('group_123/https://api.test.com/path/to/resource')
+ * // => { groupId: 'group_123', filename: 'https://api.test.com/path/to/resource' }
+ */
+function parsePath(pathStr, defaultGroupId = 'default') {
+  if (!pathStr) {
+    throw new Error('路径不能为空')
+  }
+
+  // 查找第一个斜杠的位置
+  const firstSlashIndex = pathStr.indexOf('/')
+
+  // 如果没有斜杠,整个字符串就是文件名
+  if (firstSlashIndex === -1) {
+    return {
+      groupId: defaultGroupId,
+      filename: pathStr,
+    }
+  }
+
+  // 提取组ID (第一个斜杠之前的部分)
+  const groupId = pathStr.substring(0, firstSlashIndex)
+
+  // 提取文件名 (第一个斜杠之后的所有内容,支持文件名中包含斜杠)
+  const filename = pathStr.substring(firstSlashIndex + 1)
+
+  return { groupId, filename }
+}
+
+/**
+ * 解析配置键为组ID和文件名
+ *
+ * 配置键格式: "group.{groupId}.file.{filename}"
+ * 这是旧架构在 properties 文件中存储文件配置的键格式
+ *
+ * @param {string} key - 配置键字符串
+ * @returns {{groupId: string, filename: string}} 解析结果
+ * @throws {Error} 配置键格式不正确时抛出异常
+ *
+ * @example
+ * parseConfigKey('group.default.file.https://api.test.com/users')
+ * // => { groupId: 'default', filename: 'https://api.test.com/users' }
+ *
+ * parseConfigKey('group.group_123.file.https://api.test.com/users')
+ * // => { groupId: 'group_123', filename: 'https://api.test.com/users' }
+ *
+ * parseConfigKey('invalid-key')
+ * // => 抛出 Error: 配置键格式不正确
+ */
+function parseConfigKey(key) {
+  if (!key || typeof key !== 'string') {
+    throw new Error('配置键不能为空')
+  }
+
+  // 按 ".file." 分割,应该得到2部分
+  const parts = key.split('.file.')
+  if (parts.length !== 2) {
+    throw new Error(`配置键格式不正确: ${key}, 应为 "group.{groupId}.file.{filename}"`)
+  }
+
+  // 从第一部分提取组ID (去除 "group." 前缀)
+  const groupId = parts[0].replace('group.', '')
+
+  // 第二部分就是文件名
+  const filename = parts[1]
+
+  // 验证解析结果
+  if (!groupId || !filename) {
+    throw new Error(`配置键解析失败: groupId="${groupId}", filename="${filename}"`)
+  }
+
+  return { groupId, filename }
+}
+
+/**
+ * 构建完整路径
+ *
+ * @param {string} groupId - 组ID
+ * @param {string} filename - 文件名
+ * @returns {string} 格式: "groupId/filename"
+ *
+ * @example
+ * buildPath('default', 'https://api.test.com/users')
+ * // => 'default/https://api.test.com/users'
+ */
+function buildPath(groupId, filename) {
+  return `${groupId}/${filename}`
+}
+
+/**
+ * 构建配置键
+ *
+ * @param {string} groupId - 组ID
+ * @param {string} filename - 文件名
+ * @returns {string} 格式: "group.{groupId}.file.{filename}"
+ *
+ * @example
+ * buildConfigKey('default', 'https://api.test.com/users')
+ * // => 'group.default.file.https://api.test.com/users'
+ */
+function buildConfigKey(groupId, filename) {
+  return `group.${groupId}.file.${filename}`
+}
+
+module.exports = {
+  parsePath,
+  parseConfigKey,
+  buildPath,
+  buildConfigKey,
+}

package/lib/utils/performance.js

@@ -0,0 +1,265 @@
+/**
+ * 文件名: performance.js
+ * 功能: 性能监控工具,用于测量函数执行时间
+ * 依赖: logger.js
+ * 更新: 2025-12-02
+ *
+ * 使用示例:
+ * ```javascript
+ * const { measureTime, createTimer } = require('./performance')
+ *
+ * // 方式1: 包装函数
+ * const measuredFn = measureTime(myFunc, 'MyOperation')
+ * await measuredFn(arg1, arg2)
+ *
+ * // 方式2: 手动计时
+ * const timer = createTimer('ExportOperation')
+ * // ... 执行操作
+ * timer.end() // 输出耗时
+ * ```
+ *
+ * 注意事项:
+ * - 耗时超过1秒时会输出警告日志
+ * - 开发环境下会输出所有计时日志
+ */
+
+const { createLogger } = require('./logger')
+
+/**
+ * 包装函数,自动记录执行时间
+ *
+ * 适用于需要监控性能的函数
+ * - 开发环境: 所有调用都输出日志
+ * - 生产环境: 仅耗时超过1秒时输出
+ *
+ * @param {Function} fn - 要监控的函数
+ * @param {string} operationName - 操作名称
+ * @param {Object} options - 配置选项
+ * @param {number} options.threshold - 耗时阈值(ms),超过此值才输出日志 (默认: 1000)
+ * @param {boolean} options.alwaysLog - 是否总是输出日志 (默认: false)
+ * @returns {Function} 包装后的函数
+ *
+ * @example
+ * const measuredExport = measureTime(exportGroup, '导出组')
+ * await measuredExport(groupId)
+ * // 如果耗时超过1秒,输出: [mockbubu 2025/12/02 15:30:45] 导出组 耗时: 1234ms
+ *
+ * @example
+ * // 总是输出日志
+ * const measuredQuery = measureTime(
+ *   queryFiles,
+ *   '查询文件',
+ *   { alwaysLog: true }
+ * )
+ */
+function measureTime(fn, operationName, options = {}) {
+  const {
+    threshold = 1000,
+    alwaysLog = false,
+  } = options
+
+  return async function (...args) {
+    const logger = createLogger()
+    const startTime = Date.now()
+
+    try {
+      const result = await fn.apply(this, args)
+      const duration = Date.now() - startTime
+
+      // 判断是否需要输出日志
+      const shouldLog = (
+        alwaysLog ||
+        process.env.NODE_ENV === 'development' ||
+        duration > threshold
+      )
+
+      if (shouldLog) {
+        if (duration > threshold) {
+          logger.warn(`${operationName} 耗时: ${duration}ms (超过阈值 ${threshold}ms)`)
+        } else {
+          logger.info(`${operationName} 耗时: ${duration}ms`)
+        }
+      }
+
+      return result
+    } catch (err) {
+      const duration = Date.now() - startTime
+      logger.error(`${operationName} 失败 (耗时: ${duration}ms):`, err.message)
+      throw err
+    }
+  }
+}
+
+/**
+ * 创建性能计时器
+ *
+ * 适用于需要手动控制计时开始和结束的场景
+ *
+ * @param {string} label - 计时器标签
+ * @param {Object} options - 配置选项
+ * @param {number} options.threshold - 耗时阈值(ms),超过此值输出警告 (默认: 1000)
+ * @returns {Object} 计时器对象
+ * @property {Function} end - 结束计时并输出日志
+ * @property {Function} getDuration - 获取当前耗时(不结束计时)
+ * @property {Function} checkpoint - 记录检查点
+ *
+ * @example
+ * const timer = createTimer('导出操作')
+ * // ... 步骤1
+ * timer.checkpoint('文件复制')
+ * // ... 步骤2
+ * timer.checkpoint('压缩打包')
+ * // ... 步骤3
+ * timer.end() // 输出总耗时和各检查点耗时
+ *
+ * @example
+ * const timer = createTimer('复杂操作', { threshold: 2000 })
+ * // ... 执行操作
+ * const duration = timer.getDuration() // 获取当前耗时(不结束)
+ * // ... 继续操作
+ * timer.end() // 结束并输出日志
+ */
+function createTimer(label, options = {}) {
+  const {
+    threshold = 1000,
+  } = options
+
+  const logger = createLogger()
+  const startTime = Date.now()
+  const checkpoints = []
+
+  return {
+    /**
+     * 记录检查点
+     * @param {string} checkpointLabel - 检查点标签
+     */
+    checkpoint(checkpointLabel) {
+      const duration = Date.now() - startTime
+      checkpoints.push({
+        label: checkpointLabel,
+        time: duration,
+      })
+      logger.info(`  ✓ ${checkpointLabel} (${duration}ms)`)
+    },
+
+    /**
+     * 结束计时并输出日志
+     * @returns {number} 总耗时(ms)
+     */
+    end() {
+      const duration = Date.now() - startTime
+
+      // 输出总耗时
+      if (duration > threshold) {
+        logger.warn(`${label} 总耗时: ${duration}ms (超过阈值 ${threshold}ms)`)
+      } else {
+        logger.info(`${label} 总耗时: ${duration}ms`)
+      }
+
+      // 如果有检查点,输出详细信息
+      if (checkpoints.length > 0) {
+        logger.info('  检查点明细:')
+        checkpoints.forEach((cp, index) => {
+          const prevTime = index > 0 ? checkpoints[index - 1].time : 0
+          const stepDuration = cp.time - prevTime
+          logger.info(`    ${index + 1}. ${cp.label}: ${stepDuration}ms`)
+        })
+      }
+
+      return duration
+    },
+
+    /**
+     * 获取当前耗时(不结束计时)
+     * @returns {number} 当前耗时(ms)
+     */
+    getDuration() {
+      return Date.now() - startTime
+    },
+  }
+}
+
+/**
+ * 创建性能分析器 (用于分析代码瓶颈)
+ *
+ * @param {string} label - 分析器标签
+ * @returns {Object} 分析器对象
+ *
+ * @example
+ * const profiler = createProfiler('API查询')
+ *
+ * profiler.start('数据库查询')
+ * // ... 数据库操作
+ * profiler.end()
+ *
+ * profiler.start('数据处理')
+ * // ... 数据处理
+ * profiler.end()
+ *
+ * profiler.report() // 输出性能报告
+ */
+function createProfiler(label) {
+  const logger = createLogger()
+  const records = []
+  let currentRecord = null
+
+  return {
+    /**
+     * 开始记录
+     */
+    start(operationName) {
+      if (currentRecord) {
+        logger.warn(`前一个操作 "${currentRecord.name}" 未结束`)
+      }
+      currentRecord = {
+        name: operationName,
+        startTime: Date.now(),
+      }
+    },
+
+    /**
+     * 结束记录
+     */
+    end() {
+      if (!currentRecord) {
+        logger.warn('没有正在进行的操作')
+        return
+      }
+      currentRecord.duration = Date.now() - currentRecord.startTime
+      records.push(currentRecord)
+      currentRecord = null
+    },
+
+    /**
+     * 输出性能报告
+     */
+    report() {
+      if (records.length === 0) {
+        logger.info(`${label}: 无性能数据`)
+        return
+      }
+
+      const totalDuration = records.reduce((sum, r) => sum + r.duration, 0)
+      logger.info(`${label} 性能报告 (总耗时: ${totalDuration}ms):`)
+
+      records.forEach((record, index) => {
+        const percentage = ((record.duration / totalDuration) * 100).toFixed(1)
+        logger.info(`  ${index + 1}. ${record.name}: ${record.duration}ms (${percentage}%)`)
+      })
+    },
+
+    /**
+     * 重置分析器
+     */
+    reset() {
+      records.length = 0
+      currentRecord = null
+    },
+  }
+}
+
+module.exports = {
+  measureTime,
+  createTimer,
+  createProfiler,
+}