whistle.mockbubu 2.0.0 → 2.1.0

package/lib/storage/storage-adapter.js

@@ -0,0 +1,712 @@
+/**
+ * 文件名: storage-adapter.js
+ * 功能: Storage Adapter - V3 存储适配层
+ * 依赖: storage-v3.js, logger.js, path-utils.js, error-handler.js
+ * 更新: 2025-12-05
+ *
+ * 职责:
+ * - 封装 V3 FileSystemStorage,提供统一的存储接口
+ * - 处理路径解析、分组逻辑、错误处理
+ * - 为上层路由和中间件提供简洁的 API
+ *
+ * 设计模式:
+ * - 适配器模式: 封装底层存储实现细节
+ * - 单例模式: 全局共享存储实例
+ *
+ * 使用示例:
+ * ```javascript
+ * const adapter = new StorageAdapter({ baseDir: '~/.whistle' })
+ * await adapter.init()
+ * await adapter.writeFile('default/https://api.test.com', '{"data": {...}}')
+ * const content = await adapter.readFile('default/https://api.test.com')
+ * ```
+ */
+
+const FileSystemStorage = require('./storage-v3')
+const path = require('path')
+const { createLogger } = require('../utils/logger')
+const { parsePath, parseConfigKey } = require('../utils/path-utils')
+const { withErrorHandling } = require('../utils/error-handler')
+
+/**
+ * StorageAdapter 类
+ * V3 文件系统存储的适配层,提供统一的存储接口
+ */
+class StorageAdapter {
+  /**
+   * 构造函数
+   *
+   * @param {Object} options - 配置选项
+   * @param {string} options.baseDir - 基础目录路径（可选）
+   *
+   * @example
+   * const adapter = new StorageAdapter({
+   *   baseDir: '~/.whistle'
+   * })
+   */
+  constructor(options) {
+    // 初始化 logger
+    this.logger = createLogger('storage-adapter')
+
+    // 计算基础目录路径
+    let baseDir = path.join(
+      process.env.HOME,
+      '.WhistleAppData/.whistle/.plugins/whistle.mockbubu',
+    )
+    if (options.baseDir) {
+      baseDir = `${options.baseDir}/.plugins/whistle.mockbubu`
+    }
+
+    // 记录基础目录（生产环境可保留，便于问题排查）
+    this.logger.log('基础目录:', baseDir)
+
+    // 初始化 V3 存储实例
+    this.v3Storage = new FileSystemStorage(baseDir)
+    this.currentGroupId = 'default'
+    this.initialized = false
+  }
+
+  /**
+   * 初始化存储适配器
+   * 必须在使用前调用，负责初始化底层 V3 存储并加载当前组ID
+   *
+   * @returns {Promise<void>}
+   *
+   * @example
+   * const adapter = new StorageAdapter(options)
+   * await adapter.init() // 必须先初始化
+   * await adapter.readFile('default/test.json')
+   */
+  async init() {
+    if (this.initialized) return
+
+    // 初始化 V3 存储（创建目录结构、加载元数据等）
+    await this.v3Storage.init()
+
+    // 从文件系统加载当前激活的组ID
+    this.currentGroupId = await this.v3Storage.getCurrentGroupId()
+
+    this.initialized = true
+    this.logger.log('存储适配器初始化完成，当前组:', this.currentGroupId)
+  }
+
+  /**
+   * 确保已初始化（内部方法）
+   * 所有对外API调用前都应该先调用此方法
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _ensureInit() {
+    if (!this.initialized) {
+      await this.init()
+    }
+  }
+
+  /**
+   * 设置当前激活的组ID
+   * 会持久化到文件系统，重启后仍然有效
+   *
+   * @param {string} groupId - 组ID
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await adapter.setCurrentGroupId('group_123')
+   */
+  async setCurrentGroupId(groupId) {
+    this.currentGroupId = groupId
+
+    // V3 架构：持久化到文件系统（写入组元数据）
+    if (this.getV3Storage) {
+      const v3Storage = this.getV3Storage()
+      await v3Storage.setCurrentGroupId(groupId)
+    }
+
+    this.logger.log('切换当前组:', groupId)
+  }
+
+  /**
+   * 获取当前激活的组ID
+   * 从文件系统读取，确保获取最新值
+   *
+   * @returns {Promise<string>} 当前组ID
+   *
+   * @example
+   * const currentGroup = await adapter.getCurrentGroupId()
+   * console.log('当前组:', currentGroup)
+   */
+  async getCurrentGroupId() {
+    // V3 架构：从文件系统读取（确保获取最新值）
+    if (this.getV3Storage) {
+      const v3Storage = this.getV3Storage()
+      this.currentGroupId = await v3Storage.getCurrentGroupId()
+    }
+    return this.currentGroupId
+  }
+
+  // ========================================
+  // 文件操作 API
+  // ========================================
+
+  /**
+   * 读取文件内容
+   * 通过 URL 查找文件，返回 session 数据的 JSON 字符串
+   *
+   * 工作流程:
+   * 1. 解析路径得到 groupId 和 filename（URL）
+   * 2. 强制刷新索引缓存（避免读到过期数据）
+   * 3. 从索引中根据 URL 查找 fileId
+   * 4. 使用 fileId 读取完整文件数据
+   * 5. 返回 session 数据的 JSON 字符串
+   *
+   * @param {string} name - 文件路径（格式：{groupId}/{filename}）
+   * @returns {Promise<string|null>} session 数据的 JSON 字符串，不存在返回 null
+   *
+   * @example
+   * const data = await adapter.readFile('default/https://api.test.com/users')
+   * const session = JSON.parse(data)
+   * console.log(session.res.body) // 响应内容
+   */
+  async readFile(name) {
+    await this._ensureInit()
+
+    try {
+      // 解析路径：提取 groupId 和 filename（URL）
+      const { groupId, filename } = parsePath(name, this.currentGroupId)
+
+      // 强制刷新索引缓存，确保读取最新数据
+      // 这很重要：避免删除文件后立即读取时读到旧缓存
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 从索引查找对应的 fileId
+      // 注意：V3 架构中 fileId 是随机生成的，无法从 URL 推导
+      const index = await this.v3Storage.getIndex(groupId)
+      const entry = index.files.find(f => f.url === filename)
+
+      if (!entry) {
+        this.logger.warn(`文件不存在: ${filename}`)
+        return null
+      }
+
+      // 使用索引中的 fileId 读取完整文件数据
+      const file = await this.v3Storage.getFile(groupId, entry.id)
+
+      if (!file) {
+        this.logger.warn(`文件不存在: ${groupId}/${entry.id}`)
+        return null
+      }
+
+      // ✅ V3 架构：session 数据存储在 file.json 的 session 字段中
+      // 直接从文件数据读取 session
+      const sessionData = file.session
+
+      if (!sessionData) {
+        this.logger.warn(`session 数据为空: ${groupId}/${entry.id}`)
+        return null
+      }
+
+      // 返回 session 数据的 JSON 字符串
+      return JSON.stringify(sessionData)
+    } catch (err) {
+      this.logger.error('readFile 失败:', err.message)
+      return null
+    }
+  }
+
+  /**
+   * 写入文件（创建或更新）
+   * 接收 session 数据的 JSON 字符串，自动判断是新建还是更新
+   *
+   * 工作流程:
+   * 1. 解析路径得到 groupId 和 filename
+   * 2. 尝试解析 JSON 数据为 session 对象
+   * 3. 强制刷新索引缓存
+   * 4. 查找是否已存在相同 URL 的文件
+   * 5. 存在则更新，不存在则创建新文件
+   *
+   * 错误处理:
+   * - JSON 解析失败时，会构造最小可用的 session 对象并标记错误
+   * - 存储失败不会抛出异常，避免影响正常请求流程
+   *
+   * @param {string} name - 文件路径（格式：{groupId}/{filename}）
+   * @param {string} data - session 数据的 JSON 字符串
+   * @returns {Promise<void>}
+   *
+   * @example
+   * const session = {
+   *   req: { method: 'GET', url: '/users', headers: {...} },
+   *   res: { statusCode: 200, headers: {...}, body: '{"data": [...]}' }
+   * }
+   * await adapter.writeFile('default/https://api.test.com/users', JSON.stringify(session))
+   */
+  async writeFile(name, data) {
+    await this._ensureInit()
+
+    const { groupId, filename } = parsePath(name, this.currentGroupId)
+
+    try {
+      // 1. 解析 session 数据
+      let session
+      let hasParseError = false
+
+      try {
+        session = JSON.parse(data)
+        this.logger.log(`JSON 解析成功: method=${session.req?.method}, status=${session.res?.statusCode}`)
+      } catch (parseErr) {
+        // JSON 解析失败 - 可能是非标准格式，但仍然保存（宽容处理）
+        this.logger.warn(`JSON 解析失败，将保存原始数据: ${filename}`)
+        this.logger.warn(`解析错误: ${parseErr.message}`)
+        hasParseError = true
+
+        // 构造最小可用的 session 对象，保存原始响应数据
+        session = {
+          req: {
+            method: 'UNKNOWN',
+            headers: {},
+          },
+          res: {
+            statusCode: 0,
+            headers: {},
+            body: data, // 保存原始的未解析数据
+          },
+          _parseError: parseErr.message, // 标记解析错误，便于后续排查
+        }
+      }
+
+      // 2. 强制刷新索引缓存（确保查询到最新状态）
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 3. 从索引查找是否已有相同 URL 的文件
+      const index = await this.v3Storage.getIndex(groupId)
+      const existingEntry = index.files.find(f => f.url === filename)
+
+      if (existingEntry) {
+        // 4a. 更新现有文件（使用已有的 fileId）
+        this.logger.log(`更新现有文件: ${existingEntry.id}`)
+        await this.v3Storage.updateFile(groupId, existingEntry.id, {
+          session,
+          updateTime: Date.now(),
+          hasParseError, // 标记是否有解析错误
+        })
+        this.logger.log(`文件更新成功${hasParseError ? ' (包含解析错误)' : ''}`)
+      } else {
+        // 4b. 创建新文件（生成新的随机 fileId）
+        const newFileId = this.v3Storage.generateFileId()
+        this.logger.log(`创建新文件: ${newFileId}`)
+        await this.v3Storage.createFile(groupId, newFileId, {
+          url: filename,
+          method: session.req?.method || 'UNKNOWN',
+          status: session.res?.statusCode || 0,
+          headers: session.res?.headers || {},
+          session,
+          config: {
+            mock: false, // 默认不启用 mock
+            locked: false, // 默认不锁定
+            mockVersion: 'source', // 默认使用原始版本
+          },
+          hasParseError, // 标记是否有解析错误
+        })
+        this.logger.log(`文件创建成功${hasParseError ? ' (包含解析错误)' : ''}`)
+      }
+    } catch (err) {
+      // 存储层错误 - 记录但不抛出，避免影响正常流量
+      // 这个设计很重要：存储失败不应该导致用户请求失败
+      this.logger.error(`写入文件失败: ${filename}`)
+      this.logger.error(`错误详情: ${err.message}`)
+
+      // 仅在开发环境输出堆栈
+      if (process.env.NODE_ENV === 'development') {
+        this.logger.error('错误堆栈:', err.stack)
+      }
+      // 不再抛出错误，避免中断请求流程
+    }
+  }
+
+  /**
+   * 删除文件
+   * 根据 URL 查找文件并删除（包括所有版本数据）
+   *
+   * 工作流程:
+   * 1. 解析路径得到 groupId 和 filename
+   * 2. 强制刷新索引缓存
+   * 3. 从索引中根据 URL 查找 fileId
+   * 4. 使用 fileId 删除文件（包括目录和所有版本）
+   *
+   * 错误处理:
+   * - 文件不存在也视为成功（幂等操作）
+   *
+   * @param {string} name - 文件路径（格式：{groupId}/{filename}）
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await adapter.removeFile('default/https://api.test.com/users')
+   */
+  async removeFile(name) {
+    await this._ensureInit()
+
+    const { groupId, filename } = parsePath(name, this.currentGroupId)
+
+    try {
+      // 强制刷新索引缓存（确保查询到最新状态）
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 从索引查找对应的 fileId
+      const index = await this.v3Storage.getIndex(groupId)
+      const entry = index.files.find(f => f.url === filename)
+
+      if (!entry) {
+        this.logger.warn(`文件不存在，无需删除: ${filename}`)
+        return // 幂等操作：文件不存在也视为成功
+      }
+
+      this.logger.log(`删除文件: ${entry.id} (${filename})`)
+      await this.v3Storage.deleteFile(groupId, entry.id)
+      this.logger.log('删除成功')
+    } catch (err) {
+      this.logger.error('删除失败:', err.message)
+
+      // 仅在开发环境输出堆栈
+      if (process.env.NODE_ENV === 'development') {
+        this.logger.error('错误堆栈:', err.stack)
+      }
+      // 文件不存在也视为成功，不抛出异常
+    }
+  }
+
+  /**
+   * 获取所有组的文件列表
+   * 返回所有组中所有文件的列表
+   *
+   * 工作流程:
+   * 1. 获取所有组列表
+   * 2. 遍历每个组，获取文件列表
+   * 3. 构造文件对象（格式：{groupId}/{url}）
+   *
+   * @returns {Promise<Array>} 文件列表，每个文件包含 name 和 size
+   *
+   * @example
+   * const files = await adapter.getFileList()
+   * files.forEach(file => {
+   *   console.log(file.name, file.size)
+   * })
+   */
+  async getFileList() {
+    await this._ensureInit()
+
+    try {
+      const groups = await this.v3Storage.listGroups()
+      const allFiles = []
+
+      for (const group of groups) {
+        const files = await this.v3Storage.listFiles(group.id)
+
+        files.forEach(file => {
+          // 构造文件名（格式：{groupId}/{url}）
+          const name = `${group.id}/${file.url}`
+
+          allFiles.push({
+            name, // 文件路径标识
+            size: file.size || 0, // 文件大小（字节）
+          })
+        })
+      }
+
+      return allFiles
+    } catch (err) {
+      this.logger.error('getFileList 失败:', err.message)
+      return [] // 失败时返回空数组，避免中断业务
+    }
+  }
+
+  // ========================================
+  // 属性操作 API
+  // ========================================
+
+  /**
+   * 获取属性
+   * @param {string} key - 属性键
+   */
+  async getProperty(key) {
+    await this._ensureInit()
+
+    try {
+      // 特殊处理：组列表
+      if (key === '__groups__') {
+        return await this._getGroupsProperty()
+      }
+
+      // 特殊处理：组文件配置
+      if (key.startsWith('group.') && key.includes('.file.')) {
+        return await this._getFileConfigProperty(key)
+      }
+
+      // 全局配置：从 V3 storage 的 _meta.json.config 读取
+      return await this.v3Storage.getConfig(key)
+    } catch (err) {
+      return null
+    }
+  }
+
+  /**
+   * 设置属性
+   * @param {string} key - 属性键
+   * @param {*} value - 属性值
+   */
+  async setProperty(key, value) {
+    await this._ensureInit()
+
+    try {
+      // 特殊处理：组列表
+      if (key === '__groups__') {
+        // 新架构不需要手动管理组列表
+        return
+      }
+
+      // 特殊处理：组文件配置
+      if (key.startsWith('group.') && key.includes('.file.')) {
+        await this._setFileConfigProperty(key, value)
+        return
+      }
+
+      // 全局配置：写入 V3 storage 的 _meta.json.config
+      await this.v3Storage.setConfig(key, value)
+    } catch (err) {
+      console.error('[storage-adapter] setProperty failed:', key, err.message)
+    }
+  }
+
+  /**
+   * 检查属性是否存在
+   * @param {string} key - 属性键
+   */
+  async hasProperty(key) {
+    await this._ensureInit()
+
+    const value = await this.getProperty(key)
+    return value !== null && value !== undefined
+  }
+
+  /**
+   * 检查文件是否在索引中（用于 Issue #4 检测）
+   *
+   * 与 hasProperty 的区别：
+   * - hasProperty：检查物理文件是否存在
+   * - hasFileInIndex：检查索引中是否有记录（即使物理文件被删除）
+   *
+   * 使用场景:
+   * - 检测删除后立即捕获时，索引可能还有记录但物理文件已删除
+   * - 用于诊断文件系统和索引不一致的问题
+   *
+   * @param {string} key - 配置键，格式：group.{groupId}.file.{filename}
+   * @returns {Promise<boolean>} 索引中是否存在该文件
+   *
+   * @example
+   * const exists = await adapter.hasFileInIndex('group.default.file.https://api.test.com/users')
+   * if (!exists) {
+   *   console.log('索引中不存在该文件')
+   * }
+   */
+  async hasFileInIndex(key) {
+    await this._ensureInit()
+
+    try {
+      // 1. 验证配置键格式
+      if (!key.startsWith('group.') || !key.includes('.file.')) {
+        return false
+      }
+
+      // 2. 解析配置键得到 groupId 和 filename
+      const { groupId, filename } = parseConfigKey(key)
+
+      // 3. 强制刷新索引缓存，确保读取最新数据
+      // 这很重要：避免删除后立即捕获时读到旧缓存
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 4. 检查索引中是否存在（通过 URL 而不是 fileId）
+      // 注意：V3 架构中 fileId 是创建时生成的随机ID
+      const index = await this.v3Storage.getIndex(groupId)
+      const exists = index.files.some(f => f.url === filename)
+
+      return exists
+    } catch (err) {
+      this.logger.error('hasFileInIndex 失败:', err.message)
+      return false // 失败时返回 false，视为不存在
+    }
+  }
+
+  /**
+   * 通过 URL 获取文件索引条目
+   *
+   * @param {string} groupId - 组ID
+   * @param {string} url - 文件URL
+   * @returns {Promise<Object|null>} 文件索引条目，不存在返回 null
+   */
+  async getFileByUrl(groupId, url) {
+    await this._ensureInit()
+
+    try {
+      // 强制刷新索引缓存，确保读取最新数据
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 从索引中查找 URL 匹配的文件
+      const index = await this.v3Storage.getIndex(groupId)
+      const file = index.files.find(f => f.url === url)
+
+      return file || null
+    } catch (err) {
+      this.logger.error('getFileByUrl 失败:', err.message)
+      return null
+    }
+  }
+
+  // ========================================
+  // 内部辅助方法
+  // ========================================
+
+  /**
+   * 注意：原来的 _parsePath 和 _parseConfigKey 方法已移除
+   * 现在统一使用从 path-utils.js 导入的 parsePath 和 parseConfigKey
+   */
+
+  /**
+   * 获取组列表属性（兼容旧格式）
+   * 内部方法，用于处理 __groups__ 属性查询
+   *
+   * @private
+   * @returns {Promise<Object>} 组列表对象
+   * @property {Array} groups - 组列表
+   * @property {string} currentGroupId - 当前激活的组ID
+   *
+   * @example
+   * const groupsData = await this._getGroupsProperty()
+   * console.log(groupsData.currentGroupId)
+   * groupsData.groups.forEach(g => console.log(g.name))
+   */
+  async _getGroupsProperty() {
+    const groups = await this.v3Storage.listGroups()
+    const currentGroupId = await this.v3Storage.getCurrentGroupId()
+
+    return {
+      groups: groups.map(g => ({
+        id: g.id,
+        name: g.name,
+        description: g.description,
+        createTime: g.createTime,
+        updateTime: g.updateTime,
+        isDefault: g.isDefault,
+      })),
+      currentGroupId,
+    }
+  }
+
+  /**
+   * 获取文件配置属性（兼容旧格式）
+   * 内部方法，用于处理 group.{groupId}.file.{filename} 格式的配置查询
+   *
+   * @private
+   * @param {string} key - 配置键，格式：group.{groupId}.file.{filename}
+   * @returns {Promise<Object|null>} 文件配置对象，不存在返回 null
+   *
+   * @example
+   * const config = await this._getFileConfigProperty('group.default.file.https://api.test.com/users')
+   * if (config) {
+   *   console.log('Mock状态:', config.mock)
+   *   console.log('锁定状态:', config.locked)
+   * }
+   */
+  async _getFileConfigProperty(key) {
+    const { groupId, filename } = parseConfigKey(key)
+
+    try {
+      // 强制刷新索引缓存
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 从索引查找对应的 fileId
+      const index = await this.v3Storage.getIndex(groupId)
+      const entry = index.files.find(f => f.url === filename)
+
+      if (!entry) {
+        return null
+      }
+
+      const file = await this.v3Storage.getFile(groupId, entry.id)
+
+      // 返回兼容旧格式的配置对象
+      return {
+        ...file.config,
+        url: file.url,
+        method: file.method,
+        status: file.status,
+        date: file.createTime,
+      }
+    } catch (err) {
+      this.logger.error('_getFileConfigProperty 失败:', err.message)
+      return null
+    }
+  }
+
+  /**
+   * 设置文件配置属性
+   * 内部方法，用于处理 group.{groupId}.file.{filename} 格式的配置更新
+   *
+   * @private
+   * @param {string} key - 配置键，格式：group.{groupId}.file.{filename}
+   * @param {Object} value - 配置值（会与现有配置合并）
+   * @returns {Promise<void>}
+   *
+   * @example
+   * await this._setFileConfigProperty(
+   *   'group.default.file.https://api.test.com/users',
+   *   { mock: true, locked: true }
+   * )
+   */
+  async _setFileConfigProperty(key, value) {
+    const { groupId, filename } = parseConfigKey(key)
+
+    try {
+      // 强制刷新索引缓存
+      this.v3Storage.invalidateIndex(groupId)
+
+      // 从索引查找对应的 fileId
+      const index = await this.v3Storage.getIndex(groupId)
+      const entry = index.files.find(f => f.url === filename)
+
+      if (!entry) {
+        this.logger.error('_setFileConfigProperty: 文件不存在:', filename)
+        return
+      }
+
+      const file = await this.v3Storage.getFile(groupId, entry.id)
+
+      // 合并配置（保留原有配置，覆盖新值）
+      await this.v3Storage.updateFile(groupId, entry.id, {
+        config: {
+          ...file.config,
+          ...value,
+        },
+      })
+    } catch (err) {
+      this.logger.error('_setFileConfigProperty 失败:', err.message)
+    }
+  }
+
+  // ========================================
+  // 新增：直接访问 V3 Storage
+  // ========================================
+
+  /**
+   * 获取底层的 V3 Storage 实例
+   * 用于需要直接使用 V3 API 的场景（如版本管理、批量操作等）
+   *
+   * @returns {FileSystemStorage} V3 存储实例
+   *
+   * @example
+   * const v3Storage = adapter.getV3Storage()
+   * await v3Storage.createVersion(groupId, fileId, 'v1', {...})
+   */
+  getV3Storage() {
+    return this.v3Storage
+  }
+}
+
+module.exports = StorageAdapter