whistle.mockbubu 2.0.0 → 2.1.1

package/README.md

@@ -117,3 +117,41 @@ pattern mockbubu://  或者 pattern mockbubu://pathname
 - mock 返回内容使用当前选中的版本
 
 [![step2.png](https://i.postimg.cc/K8wsg8xv/step2.png)](https://postimg.cc/Js3Qfms9)
+
+---
+
+## 开发者文档
+
+如果你需要参与 whistle.mockbubu 的开发、维护或迭代，请阅读以下文档：
+
+📖 **[开发者指南 (DEVELOPER-GUIDE.md)](./docs/DEVELOPER-GUIDE.md)**
+
+包含以下内容：
+- 项目架构设计
+- 完整业务流程
+- 关键业务逻辑和判断
+- 数据存储设计
+- API 接口清单
+- 重要注意事项
+- 迭代开发指南（影响范围和可行性分析）
+- 故障排查指南
+- 编码规范
+
+📋 **[编码规范 (CODE-STANDARDS.md)](./docs/CODE-STANDARDS.md)**
+
+代码质量标准和最佳实践
+
+---
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。在提交 PR 前，请确保：
+
+1. 阅读了开发者指南
+2. 遵循编码规范
+3. 测试了所有相关功能
+4. 更新了相关文档
+
+## License
+
+MIT

package/index.js

@@ -1,10 +1,10 @@
 exports.uiServer = require('./lib/uiServer')
-// exports.rulesServer = require('./lib/rulesServer')
+exports.rulesServer = require('./lib/core/rulesServer')
 // exports.tunnelRulesServer = require('./lib/tunnelRulesServer');
-exports.resRulesServer = require('./lib/resRulesServer')
+exports.resRulesServer = require('./lib/core/resRulesServer')
 // exports.statsServer = require('./lib/statsServer')
 // exports.resStatsServer = require('./lib/resStatsServer')
-exports.server = require('./lib/server')
+exports.server = require('./lib/core/server-entry/server')
 // exports.reqRead = require('./lib/reqRead')
 // exports.reqWrite = require('./lib/reqWrite');
 // exports.resRead = require('./lib/resRead')

package/lib/config/const.js

@@ -0,0 +1,138 @@
+/**
+ * 文件名: const.js
+ * 功能: 全局常量定义
+ * 更新: 2025-12-02
+ *
+ * 包含:
+ * - 规则类型映射
+ * - 过滤器配置
+ * - 业务规则常量
+ * - 系统常量
+ */
+
+// ============================================
+// Whistle 规则相关常量
+// ============================================
+
+/**
+ * 规则值类型映射
+ * 用于 Whistle 规则中的 mockbubu://[mode] 参数
+ */
+exports.RuleValueMap = {
+  href: 'href', // 完整URL (包含query)
+  pathname: 'pathname', // origin + pathname (默认)
+  pattern: 'pattern', // 使用 Whistle pattern 作为文件名
+}
+
+/**
+ * 范围筛选类型映射
+ * 用于UI中的范围筛选下拉框
+ */
+exports.RangeMap = {
+  MOCKING: 'mocking', // 正在mock的文件
+  NOT_MOCKING: 'not-mocking', // 未mock的文件
+  LOCKED: 'locked', // 已锁定的文件
+}
+
+/**
+ * 范围筛选配置映射
+ * 定义每种范围筛选的具体过滤条件
+ */
+exports.RangeFilterMap = {
+  'mocking': { key: 'mock', value: true, method: 'equal' },
+  'not-mocking': { key: 'mock', value: false, method: 'equal' },
+  'locked': { key: 'locked', value: true, method: 'equal' },
+}
+
+/**
+ * 规则类型筛选配置映射
+ * 用于按规则类型 (href/pathname/pattern) 过滤文件
+ */
+exports.RuleFilterMap = {
+  'href': { key: 'ruleValue', value: 'href', method: 'equal' },
+  'pathname': { key: 'ruleValue', value: 'pathname', method: 'equal' },
+  'pattern': { key: 'ruleValue', value: 'pattern', method: 'equal' },
+}
+
+/**
+ * 锁定状态筛选配置映射
+ * 用于按锁定状态过滤文件
+ */
+exports.LockedFilterMap = {
+  'locked': { key: 'locked', value: true, method: 'equal' },
+  'unlocked': { key: 'locked', value: false, method: 'equal' },
+}
+
+// ============================================
+// 业务规则常量
+// ============================================
+
+/**
+ * 业务规则常量
+ * 定义系统的各种限制和规则
+ */
+exports.BusinessRules = {
+  // 版本管理
+  MAX_VERSIONS_PER_FILE: 10, // 每个文件最多10个版本
+  MAX_VERSION_NAME_LENGTH: 20, // 版本名最长20字符
+
+  // 组管理
+  MAX_GROUPS: 100, // 最多100个组
+
+  // 文件管理
+  MAX_FILENAME_LENGTH: 2048, // 文件名最长2048字符
+  MAX_MOCK_DATA_SIZE: 5 * 1024 * 1024, // Mock数据最大5MB
+
+  // 缓存
+  INDEX_CACHE_TTL: 60 * 1000, // 索引缓存1分钟过期 (60秒)
+  RULE_AUTO_EXPIRE_TIME: 10 * 1000, // 规则10秒无请求自动过期
+
+  // 临时文件清理
+  TEMP_DIR_MAX_AGE: 7 * 24 * 60 * 60 * 1000, // 临时目录保留7天
+  TEMP_CLEANUP_RETRIES: 3, // 临时目录清理重试3次
+  TEMP_CLEANUP_RETRY_DELAY: 100, // 重试间隔100ms
+}
+
+// ============================================
+// 系统常量
+// ============================================
+
+/**
+ * 系统常量
+ * 定义系统级别的固定值
+ */
+exports.SystemConstants = {
+  // 默认组
+  DEFAULT_GROUP_ID: 'default',
+  DEFAULT_GROUP_NAME: '默认组',
+
+  // 存储键名
+  GROUPS_META_KEY: '__groups__', // 组元数据的存储键
+  API_LIST_UPDATED_KEY: 'api-list-updated', // API列表更新标志的存储键
+  PLUGIN_ENABLED_KEY: 'mockbubu.enabled', // 插件启用状态的存储键（已废弃，保留用于迁移）
+
+  // 版本相关
+  DEFAULT_VERSION_NAME: 'source', // 默认版本名称 (原始响应)
+}
+
+// ============================================
+// 插件模式相关常量（直接导出，便于引用）
+// ============================================
+
+/**
+ * 插件工作模式的存储键
+ */
+exports.PLUGIN_MODE_KEY = 'mockbubu.mode'
+
+/**
+ * 插件工作模式枚举
+ */
+exports.PLUGIN_MODE = {
+  DEFAULT: 'default', // 默认模式：全功能（捕获新请求 + 返回Mock）
+  MOCK_ONLY: 'mock-only', // 仅Mock模式：不捕获，仅返回已开启Mock的数据
+}
+
+/**
+ * 默认插件模式
+ */
+exports.DEFAULT_PLUGIN_MODE = 'default'

package/lib/config/rule-collector.js

@@ -0,0 +1,81 @@
+/**
+ * 规则收集器 - 收集和管理生效的 Whistle 规则
+ * 用于在 UI 中显示帮助提示
+ *
+ * 设计原则：
+ * - 规则列表在每次请求到来时动态更新
+ * - API 查询前先清空，确保返回的是当前实际生效的规则
+ */
+
+class RuleCollector {
+  constructor() {
+    this.activeRules = new Set()
+    this.lastRequestTime = 0
+  }
+
+  /**
+   * 添加一条生效的规则
+   * @param {string} rule - 规则字符串，如 "*.shein.com mockbubu://pathname"
+   */
+  addRule(rule) {
+    this.activeRules.add(rule)
+    this.lastRequestTime = Date.now()
+  }
+
+  /**
+   * 开始新的收集周期（清空旧规则）
+   * 应该在 API 查询开始时调用
+   */
+  startNewCollection() {
+    this.activeRules.clear()
+    this.lastRequestTime = Date.now()
+  }
+
+  /**
+   * 获取所有生效的规则列表
+   * 如果超过10秒没有新请求，自动清空（说明规则可能已关闭）
+   * @returns {Array<string>} 规则数组
+   */
+  getRules() {
+    const now = Date.now()
+    const timeSinceLastRequest = now - this.lastRequestTime
+
+    // 如果超过10秒没有新请求，说明规则可能已关闭
+    if (this.lastRequestTime > 0 && timeSinceLastRequest > 10000) {
+      console.log('[mockbubu] 🧹 超过10秒无请求，清空规则列表')
+      this.activeRules.clear()
+      this.lastRequestTime = 0
+    }
+
+    return Array.from(this.activeRules).sort()
+  }
+
+  /**
+   * 清空所有规则
+   */
+  clear() {
+    this.activeRules.clear()
+    this.lastRequestTime = 0
+  }
+
+  /**
+   * 获取规则数量
+   * @returns {number}
+   */
+  getCount() {
+    // 获取数量时也要检查是否需要清空
+    this.getRules()
+    return this.activeRules.size
+  }
+
+  /**
+   * 获取最后一次收到请求的时间
+   * @returns {number} 时间戳
+   */
+  getLastRequestTime() {
+    return this.lastRequestTime
+  }
+}
+
+// 导出单例
+module.exports = new RuleCollector()

package/lib/constants.js

@@ -0,0 +1,62 @@
+/**
+ * 全局常量定义
+ *
+ * 用途：
+ * - 避免魔法数字
+ * - 集中管理配置
+ * - 提高代码可维护性
+ */
+
+/**
+ * 缓存容量限制
+ */
+const CACHE_LIMITS = {
+  // 后端暂存区最大容量（超出触发滑动窗口清理）
+  BACKEND_STAGING_MAX_SIZE: 200,
+
+  // 前端缓存最大容量
+  FRONTEND_CACHE_MAX_SIZE: 2000,
+
+  // 滑动窗口清理批次大小（每次清理最旧的N条）
+  CLEANUP_BATCH_SIZE: 50,
+}
+
+/**
+ * 轮询相关配置
+ */
+const POLLING_CONFIG = {
+  // 前端轮询间隔（毫秒）
+  INTERVAL: 2000,
+
+  // 首次轮询的 startTime 值
+  INITIAL_START_TIME: 0,
+}
+
+/**
+ * 文件操作相关配置
+ */
+const FILE_CONFIG = {
+  // 版本数量上限
+  MAX_VERSIONS: 10,
+
+  // 默认版本名称
+  DEFAULT_VERSION_NAME: 'source',
+}
+
+/**
+ * 日志前缀
+ */
+const LOG_PREFIX = {
+  MEMORY_BUFFER: '[MemoryBuffer]',
+  CAPTURE_HANDLER: '[CaptureHandler]',
+  API_LIST: '[ApiList]',
+  FILE_SAVE: '[FileSave]',
+  UI_SERVER: '[uiServer]',
+}
+
+module.exports = {
+  CACHE_LIMITS,
+  POLLING_CONFIG,
+  FILE_CONFIG,
+  LOG_PREFIX,
+}

package/lib/core/memory-buffer/index.js

@@ -0,0 +1,207 @@
+/**
+ * 内存缓冲区
+ *
+ * 职责：
+ * - 捕获请求后暂存,供前端拉取
+ * - URL 去重（已存在则跳过）
+ * - 容量管理（滑动窗口清理）
+ *
+ * 核心规则：
+ * - 取出即清空（无论第一次还是后续轮询）
+ *
+ * 生命周期：
+ * - 进程重启清空
+ */
+
+const { CACHE_LIMITS, LOG_PREFIX } = require('../../constants')
+
+class MemoryBuffer {
+  /**
+   * 构造函数
+   *
+   * @param {Object} options - 配置选项
+   * @param {number} options.maxSize - 最大容量
+   * @param {number} options.cleanupBatchSize - 滑动窗口清理批次大小
+   */
+  constructor(options = {}) {
+    // Key: `${groupId}/${url}`
+    // Value: { url, method, status, session, captureTime }
+    this.stagingRequests = new Map()
+
+    this.maxSize = options.maxSize || CACHE_LIMITS.BACKEND_STAGING_MAX_SIZE
+    this.cleanupBatchSize = options.cleanupBatchSize || CACHE_LIMITS.CLEANUP_BATCH_SIZE
+  }
+
+  /**
+   * 添加捕获的请求
+   *
+   * 去重规则：URL 已存在时跳过新数据（保留旧的）
+   *
+   * @param {string} groupId - 组ID
+   * @param {string} url - 请求URL
+   * @param {Object} data - 捕获数据
+   * @param {Object} data.session - 完整会话数据
+   * @param {string} data.method - HTTP方法
+   * @param {number} data.status - 状态码
+   */
+  add(groupId, url, data) {
+    // 参数校验
+    if (!groupId || !url || !data || !data.session) {
+      console.error(`${LOG_PREFIX.MEMORY_BUFFER} add 参数不完整`, {
+        hasGroupId: !!groupId,
+        hasUrl: !!url,
+        hasData: !!data,
+        hasSession: !!(data && data.session),
+      })
+      return
+    }
+
+    const key = `${groupId}/${url}`
+
+    // 去重：已存在则跳过（保留旧的）
+    if (this.stagingRequests.has(key)) {
+      console.log(`${LOG_PREFIX.MEMORY_BUFFER} 暂存区已存在,跳过: ${url}`)
+      return
+    }
+
+    // 新增到暂存区
+    this.stagingRequests.set(key, {
+      url,
+      method: data.method,
+      status: data.status,
+      session: data.session,
+      captureTime: Date.now(),
+    })
+
+    console.log(`${LOG_PREFIX.MEMORY_BUFFER} 暂存区新增: ${url} (当前容量: ${this.stagingRequests.size})`)
+
+    // 容量检查：超出上限触发滑动窗口清理
+    if (this.stagingRequests.size > this.maxSize) {
+      this.slidingWindowCleanup()
+    }
+  }
+
+  /**
+   * 获取增量数据并清空
+   *
+   * 统一的轮询逻辑：
+   * - startTime=0: 第一次轮询,返回所有数据
+   * - startTime>0: 后续轮询,返回增量数据
+   *
+   * 无论哪种情况,取出即清空
+   *
+   * @param {string} groupId - 组ID
+   * @param {number} startTime - 起始时间戳
+   * @returns {Array<Object>} 请求数据列表
+   */
+  getAndClear(groupId, startTime) {
+    // 参数校验
+    if (!groupId || typeof startTime !== 'number') {
+      console.error(`${LOG_PREFIX.MEMORY_BUFFER} getAndClear 参数不完整`, {
+        hasGroupId: !!groupId,
+        startTimeType: typeof startTime,
+      })
+      return []
+    }
+
+    const result = []
+    const keysToDelete = []
+
+    // 遍历暂存区
+    for (const [key, value] of this.stagingRequests) {
+      if (key.startsWith(`${groupId}/`)) {
+        // startTime=0: 返回所有数据（第一次轮询）
+        // startTime>0: 返回增量数据
+        if (startTime === 0 || value.captureTime > startTime) {
+          result.push(value)
+          keysToDelete.push(key)
+        }
+      }
+    }
+
+    // 取出即清空
+    keysToDelete.forEach(key => {
+      this.stagingRequests.delete(key)
+    })
+
+    if (keysToDelete.length > 0) {
+      console.log(`${LOG_PREFIX.MEMORY_BUFFER} 返回 ${result.length} 条并清空 (剩余容量: ${this.stagingRequests.size})`)
+    }
+
+    return result
+  }
+
+  /**
+   * 滑动窗口清理
+   *
+   * 清理策略：
+   * - 按 captureTime 排序（最旧的在前）
+   * - 删除最旧的 cleanupBatchSize 条数据
+   */
+  slidingWindowCleanup() {
+    const entries = Array.from(this.stagingRequests.entries())
+
+    // 按时间排序（最旧的在前）
+    entries.sort((a, b) => a[1].captureTime - b[1].captureTime)
+
+    // 删除最旧的数据
+    const toRemove = entries.slice(0, this.cleanupBatchSize)
+    toRemove.forEach(([key]) => {
+      this.stagingRequests.delete(key)
+    })
+
+    console.log(`${LOG_PREFIX.MEMORY_BUFFER} 滑动窗口清理 ${toRemove.length} 条 (剩余容量: ${this.stagingRequests.size})`)
+  }
+
+  /**
+   * 清空指定组的所有数据
+   *
+   * 场景：切换组或删除组时清理对应的暂存数据
+   *
+   * @param {string} groupId - 组ID
+   * @returns {number} 清除的数量
+   */
+  clearGroup(groupId) {
+    // 参数校验
+    if (!groupId) {
+      console.error(`${LOG_PREFIX.MEMORY_BUFFER} clearGroup 参数不完整`)
+      return 0
+    }
+
+    let clearedCount = 0
+    const keysToDelete = []
+
+    // 遍历找到该组的所有数据
+    for (const [key] of this.stagingRequests) {
+      if (key.startsWith(`${groupId}/`)) {
+        keysToDelete.push(key)
+      }
+    }
+
+    // 删除数据
+    keysToDelete.forEach(key => {
+      this.stagingRequests.delete(key)
+      clearedCount++
+    })
+
+    if (clearedCount > 0) {
+      console.log(`${LOG_PREFIX.MEMORY_BUFFER} 清空组数据: ${groupId}, 已删除 ${clearedCount} 条 (剩余容量: ${this.stagingRequests.size})`)
+    }
+
+    return clearedCount
+  }
+
+  /**
+   * 获取统计信息
+   *
+   * @returns {Object} 统计信息
+   */
+  getStats() {
+    return {
+      size: this.stagingRequests.size,
+      maxSize: this.maxSize,
+    }
+  }
+}
+
+module.exports = { MemoryBuffer }

package/lib/core/memory-buffer/shared-instance.js

@@ -0,0 +1,15 @@
+/**
+ * 共享的内存缓冲区实例
+ *
+ * 职责：
+ * - 提供单例的 MemoryBuffer 实例
+ * - 被 server.js（捕获端）和 uiServer（UI端）共享
+ * - 确保数据流转的唯一入口
+ */
+
+const { MemoryBuffer } = require('./index')
+
+// 创建单例实例
+const sharedMemoryBuffer = new MemoryBuffer()
+
+module.exports = sharedMemoryBuffer

package/lib/core/plugin-mode-manager.js

@@ -0,0 +1,74 @@
+/**
+ * 文件名: plugin-mode-manager.js
+ * 功能: 插件模式管理器（单例）
+ * 职责:
+ * - 缓存当前插件模式
+ * - 提供同步读取模式的方法
+ * - 提供异步更新模式的方法
+ */
+
+const { PLUGIN_MODE, DEFAULT_PLUGIN_MODE } = require('../config/const')
+
+/**
+ * 插件模式管理器（单例模式）
+ */
+class PluginModeManager {
+  constructor() {
+    // 当前模式缓存
+    this.currentMode = DEFAULT_PLUGIN_MODE
+    // Storage 引用（在 init 时设置）
+    this.storage = null
+  }
+
+  /**
+   * 初始化模式管理器
+   * @param {Object} storage - Whistle storage 对象
+   */
+  async init(storage) {
+    this.storage = storage
+    await this.refresh()
+    console.log(`[mockbubu] ✅ 插件模式管理器初始化完成: ${this.currentMode}`)
+  }
+
+  /**
+   * 从 storage 刷新模式缓存
+   */
+  async refresh() {
+    if (!this.storage) {
+      return
+    }
+
+    const { PLUGIN_MODE_KEY } = require('../config/const')
+    const mode = await this.storage.getProperty(PLUGIN_MODE_KEY)
+    this.currentMode = Object.values(PLUGIN_MODE).includes(mode) ? mode : DEFAULT_PLUGIN_MODE
+  }
+
+  /**
+   * 获取当前模式（同步方法）
+   * @returns {string} 'capture' | 'mock-only'
+   */
+  getMode() {
+    return this.currentMode
+  }
+
+  /**
+   * 设置模式（异步方法）
+   * @param {string} newMode - 新模式
+   */
+  async setMode(newMode) {
+    if (!Object.values(PLUGIN_MODE).includes(newMode)) {
+      throw new Error(`无效的模式: ${newMode}`)
+    }
+
+    if (!this.storage) {
+      throw new Error('Storage 未初始化')
+    }
+
+    const { PLUGIN_MODE_KEY } = require('../config/const')
+    await this.storage.setProperty(PLUGIN_MODE_KEY, newMode)
+    this.currentMode = newMode
+  }
+}
+
+// 导出单例实例
+module.exports = new PluginModeManager()

package/lib/core/resRulesServer.js

@@ -0,0 +1,14 @@
+/**
+ * Whistle resRulesServer 钩子
+ * 为使用了 Mock 数据的请求添加样式标记（在 Network 面板中显示）
+ */
+module.exports = (server, options) => {
+  server.on('request', (req, res) => {
+    // 检查响应头中是否有 x-mockbubu-mocked 标记（表示返回了 Mock 数据）
+    if (req?.headers?.['x-mockbubu-mocked'] === 'true') {
+      res.end('* style://color=@2c8bea&bgColor=@0dd142&fontStyle=bold')
+      return
+    }
+    res.end()
+  })
+}

package/lib/core/rulesServer.js

@@ -0,0 +1,31 @@
+/**
+ * rulesServer 钩子
+ * 动态返回 mockbubu 规则，根据启用状态控制
+ */
+module.exports = (server, options) => {
+  server.on('request', (req, res) => {
+    const storage = options.storage
+
+    // 从 properties 读取启用状态，默认为启用
+    const enabled = storage.getProperty('mockbubu.enabled') !== false
+
+    if (!enabled) {
+      // 禁用时返回空规则
+      console.log('[mockbubu] 🚫 插件已禁用，不返回规则')
+      res.end('')
+      return
+    }
+
+    // 启用时返回 mockbubu 规则
+    // 这里返回通配规则，让所有请求都经过 server 钩子判断
+    const rules = `
+# mockbubu 插件规则
+# 所有请求都会经过 mockbubu server 钩子处理
+# 具体是否 mock 由 server 钩子中的 mock 开关决定
+* mockbubu://
+    `.trim()
+
+    console.log('[mockbubu] ✅ 插件已启用，返回规则')
+    res.end(rules)
+  })
+}