npm - whistle.mockbubu - Versions diffs - 1.0.0-dev.4 → 2.0.0 - Mend

whistle.mockbubu 1.0.0-dev.4 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/.gitignore +4 -0
package/CHANGELOG_GROUP_FEATURE.md +468 -0
package/CHANGELOG_P0_FIXES.md +412 -0
package/CHANGELOG_P1_OPTIMIZATIONS.md +292 -0
package/CLAUDE.md +436 -0
package/GROUP_FEATURE_DESIGN.md +520 -0
package/lib/const.js +19 -0
package/lib/group-manager.js +491 -0
package/lib/server.js +173 -33
package/lib/uiServer/index.js +46 -4
package/lib/uiServer/router/group-router.js +218 -0
package/lib/uiServer/router/index.js +1393 -38
package/lib/uiServer/router/version-router.js +131 -53
package/lib/uiServer/util.js +64 -10
package/lib/uiServer/validator.js +105 -0
package/lib/utils.js +149 -27
package/package.json +1 -1
package/public/js/app.js +4541 -747
package/public/js/app.js.map +1 -1
package/public/js/chunk-vendors.js +12194 -6869
package/public/js/chunk-vendors.js.map +1 -1

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,436 @@
+# CLAUDE.md
+此文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。
+## 🎭 你的角色定位
+你是 **whistle.mockbubu** 项目的全能开发专家，具备以下综合能力：
+### 💻 技术能力
+- **前端专家**：精通 Vue.js 2.7（包括Vue3）、Element UI、现代 CSS/Less、响应式设计
+- **Node.js 专家**：精通 Koa、中间件架构、Stream 处理、异步编程
+- **Whistle 插件专家**：深入理解 Whistle 插件系统、生命周期钩子、Storage API
+- **全栈架构师**：能够设计和优化前后端交互、API 设计、状态管理
+### 🎨 产品与设计能力
+- **产品经理思维**：理解用户需求、优化用户体验、功能规划
+- **UI/UX 设计**：现代审美、交互设计、视觉层次、色彩搭配
+- **可用性专家**：注重易用性、快捷操作、反馈提示
+### 🎯 工作原则
+1. **用户优先**：始终从开发者使用体验出发，让 API mock 管理更高效
+2. **代码质量**：遵循项目代码规范，编写可维护、可测试的代码
+3. **性能意识**：优化请求处理、减少不必要的存储操作
+4. **设计一致性**：保持 UI 风格统一、交互模式一致
+5. **问题解决**：遇到问题先从代码角度分析根因，再通过调试进一步排查问题，提供完整解决方案
+### 🎯 开发规范
+#### 样式规范
+1. **优先使用现代 CSS 布局**：使用 `flex` + `gap` 替代 margin，使用 Grid 布局处理复杂场景
+2. **禁用 !important**：除非处理第三方组件样式冲突，否则禁止使用 `!important`
+3. **注意样式隔离**：
+   - Element UI 的 `el-dialog` 等组件会渲染到 `<body>` 下，scoped CSS 无效
+   - 使用 `custom-class` 属性 + 全局 `<style>` 块处理弹窗等组件
+   - 使用 `/deep/` 或 `::v-deep` 穿透组件样式（谨慎使用）
+4. **保持样式可维护性**：使用 BEM 命名规范，避免深层嵌套选择器
+#### 逻辑规范
+1. **整体思维优先**：有问题或优化时，先评估是否需要重新设计架构，而非局部打补丁
+2. **数据流清晰**：
+   - 前端：保持 props 单向数据流，使用 emit 向上通信
+   - 后端：API 返回完整数据，避免前端多次请求拼接
+3. **状态同步**：修改数据后，确保前端展示、后端存储、列表排序等所有相关状态同步更新
+4. **用户体验细节**：
+   - 弹窗打开自动聚焦到主要输入框
+   - 按钮文字根据状态动态显示（创建/编辑）
+   - Tooltip 位置避免遮挡主要操作区域
+   - 操作后提供明确的成功/失败反馈
+#### 开发工作流
+1. **使用 watch 模式**：
+   - 前端：`npm run dev` 自动编译
+   - 后端：`lack watch` 自动热重载
+   - 避免频繁手动重启服务
+2. **调试技巧**：
+   - 使用 `console.log` 添加调试日志（标注 `[mockbubu]` 前缀）
+   - 开发完成后可保留关键日志，用于生产环境排查问题
+3. **版本控制**：
+   - 功能开发使用独立分支
+   - Commit 消息清晰描述改动内容和原因
+   - 大功能拆分为多个小 commit，便于回溯
+#### 测试规范
+1. **前端测试**：修改后必须在浏览器中实际操作验证，确认功能和样式
+2. **后端测试**：使用 Postman 或 curl 测试 API，确认数据格式正确
+3. **边界测试**：测试空值、极限值（如版本数量上限）、特殊字符等
+4. **兼容性测试**：确保旧数据（无时间戳等元信息）能正常显示
+## 项目概述
+whistle.mockbubu 是一个 Whistle 扩展插件，可实时捕获和模拟 API 响应。它由集成了 Whistle 插件系统的 Node.js 后端（Koa 服务器）和用于管理 mock 文件的 Vue.js 前端组成。
+## 常用命令
+### 代码检查
+```bash
+# 检查根目录的 JavaScript 文件（后端）
+npm run lint
+# 自动修复代码检查问题
+npm run lint:fix
+# 代码检查并强制零警告（用于 CI）
+npm run lint:check
+```
+### 前端开发（在 app/ 目录下）
+```bash
+cd app
+# 开发模式构建（带监听）
+npm run dev
+# 生产模式构建（带监听）
+npm run build
+# 检查 Vue 前端代码
+npm run lint
+# 修复前端代码检查问题
+npm run lint:fix
+```
+### 安装插件
+```bash
+# 全局安装 whistle.mockbubu
+w2 install whistle.mockbubu
+```
+## 架构
+### 与 Whistle 的插件集成
+这是一个 Whistle 插件，在 `index.js` 中导出特定的钩子函数：
+- **uiServer**: 提供基于 Koa 的 Web UI 用于管理 mock 文件（端口由 Whistle 提供）
+- **resRulesServer**: 在 Whistle UI 中为拦截的请求添加样式（为缓存响应添加红色）
+- **server**: 主要的请求拦截器，捕获 API 响应并提供模拟数据
+### 后端架构 (`lib/`)
+**核心组件：**
+1. **server.js** - 主要的请求拦截逻辑：
+   - 捕获 JSON API 响应并使用 Whistle 的 storage API 存储
+   - 当文件启用 mock 模式时提供模拟响应
+   - 使用 `req.passThrough()` 在不需要 mock 时让请求正常通过
+   - 处理响应体压缩（gzip、deflate、br）
+2. **uiServer/index.js** - Koa Web 应用：
+   - 从 `public/` 目录提供 Vue 前端服务
+   - 提供用于管理 mock 文件的 REST API 端点
+   - 使用 CORS 允许前端通信
+   - 通过 `options.storage` 集成 Whistle 的存储
+3. **uiServer/router/index.js** - API 端点：
+   **文件管理**:
+   - `/cgi-bin/mockbubu/api-list` - 列出所有捕获的 API mock 并支持过滤
+   - `/cgi-bin/mockbubu/update-api-data` - 更新 mock 文件内容
+   - `/cgi-bin/mockbubu/update-api-mock` - 切换文件的 mock 开关
+   - `/cgi-bin/mockbubu/update-api-lock` - 锁定文件以防止删除
+   - `/cgi-bin/mockbubu/create-api-data` - 手动创建新 mock
+   **删除操作**:
+   - `/cgi-bin/mockbubu/delete-api` - 删除单个 mock 文件（智能删除）
+   - `/cgi-bin/mockbubu/batch-delete-by-names` - 批量删除指定文件（智能删除）
+   - `/cgi-bin/mockbubu/batch-delete-preview` - 批量删除预览
+   **存储管理**:
+   - `/cgi-bin/mockbubu/storage-stats` - 获取存储统计信息
+   - `/cgi-bin/mockbubu/preview-orphan-files` - 预览孤儿文件列表
+   - `/cgi-bin/mockbubu/cleanup-orphan-files` - 清理孤儿文件
+   - `/cgi-bin/mockbubu/preview-unused-files` - 预览未使用文件列表
+   - `/cgi-bin/mockbubu/cleanup-unused-files` - 清理未使用文件（需确认）
+   **版本管理** (`version-router.js`):
+   - 创建、编辑、删除、切换版本
+4. **utils.js** - 核心工具函数：
+   - 封装 Whistle storage API 的文件操作（`writeFile`、`readFile`、`removeFile`）
+   - mock 元数据的属性管理（mock 状态、锁定状态、时间戳）
+   - 根据模式从 URL 生成文件名（href、pathname、pattern）
+   - 每个文件的多版本管理
+   - 缓冲区/压缩处理（`handleBuffer2String`）
+5. **const.js** - 规则类型和过滤器配置的常量
+### 前端架构 (`app/src/`)
+**使用 Vue CLI 构建的 Vue 2.7 应用：**
+**主容器**:
+- **MockContainer.vue** - 主容器组件
+**内容区组件**:
+- **components/content/RequestList.vue** - 列出捕获的 API 端点
+- **components/content/RequestDetail.vue** - 显示请求详情
+- **components/content/ResponsePanel.vue** - mock 响应数据编辑器
+**头部操作区组件**:
+- **components/header/ActionPanel.vue** - 过滤器和操作控制
+**分组管理组件**:
+- **components/group/GroupSelector.vue** - 组选择下拉框
+- **components/group/GroupManager.vue** - 组管理对话框
+**存储管理组件**:
+- **components/storage/StorageManager.vue** - 存储管理对话框（Phase 1 实现）
+  - 存储统计信息展示
+  - 孤儿文件清理
+  - 未使用文件清理
+**公共组件**:
+- **components/common/JsonEditor.vue** - JSON 编辑器组件（使用 jsoneditor 库）
+### 存储模型（三层架构）
+mockbubu 采用三层数据架构设计，实现了分组功能的完全隔离：
+#### Layer 1: 物理文件（Files）
+**存储位置**: `~/.whistle/plugins/whistle.mockbubu/files/`
+**存储内容**: 实际的 HTTP 请求/响应会话数据
+**特点**:
+- ✅ 所有组共享同一份物理文件
+- ✅ 保存实际捕获的请求/响应
+- ✅ 多个组引用同一个文件名即引用同一份数据
+#### Layer 2: 全局属性（Global Properties）⚠️ 正在废弃
+**存储位置**: `~/.whistle/plugins/whistle.mockbubu/properties`
+**存储内容**: 文件的全局元数据
+**当前保留的属性**:
+- `url`: string - 原始请求 URL
+- `method`: string - HTTP 方法
+- `date`: string - 创建时间
+- `status`: number - HTTP 状态码
+- `rule`: string - Whistle 规则
+- `ruleValue`: string - 规则值（pathname/href/pattern）
+**已废弃的属性**（移至 Layer 3）:
+- ~~`mock`~~ - 移至 Layer 3（每组独立开关）
+- ~~`locked`~~ - 移至 Layer 3（每组独立锁定）
+- ~~`mockVersion`~~ - 移至 Layer 3（每组独立版本）
+**废弃计划**: 未来 Phase 2 将全局元数据移入 Layer 1 文件内部
+#### Layer 3: 组属性（Group Properties）🎯 核心层
+**存储位置**: `~/.whistle/plugins/whistle.mockbubu/properties`
+**存储内容**: 每个组对文件的独立配置
+**配置 Key 格式**: `group.{groupId}.file.{filename}`
+**配置内容**:
+```javascript
+{
+  mock: boolean,         // 是否启用 mock
+  locked: boolean,       // 是否锁定以防删除
+  mockVersion: string,   // 当前激活的版本名称
+}
+```
+**版本数据 Key 格式**: `group.{groupId}.file.{filename}.version.{versionName}`
+**特点**:
+- ✅ 每个组有完全独立的配置
+- ✅ 同一文件在不同组可以有不同的 mock 开关
+- ✅ 同一文件在不同组可以使用不同的版本
+- ✅ 实现真正的多环境隔离
+#### 三层关系图
+```
+Layer 1 (物理文件 - 共享)
+    │
+    └─► files/0.api.example.com_users (原始数据)
+            │
+            ├─► Layer 3: 组A配置 (mock: true, version: v1)
+            ├─► Layer 3: 组B配置 (mock: false, version: source)
+            └─► Layer 3: 组C配置 (mock: true, version: v2)
+```
+#### 删除策略
+根据三层架构，删除文件时采用智能删除策略：
+1. **配置删除**：仅删除 Layer 3 配置，保留 Layer 1 物理文件
+   - 当其他组仍在使用该文件时
+   - 该组将不再看到此文件，但其他组不受影响
+2. **完全删除**：删除 Layer 1 + Layer 3
+   - 当仅当前组使用该文件时
+   - 物理文件和配置全部删除
+3. **孤儿文件**：Layer 1 存在但所有组的 Layer 3 都不存在
+   - 可能由于并发删除 bug 或手动清理导致
+   - 可通过存储管理工具清理
+### 文件名生成模式
+通过 Whistle 规则中的 `mockbubu://[mode]` 控制：
+- **pathname**（默认）: `origin + pathname`（例如：`https://api.example.com/users`）
+- **href**: 完整的 URL，包括查询参数
+- **pattern**: 使用 Whistle pattern 本身作为文件名
+### 请求流程
+1. 用户配置 Whistle 规则：`pattern mockbubu://pathname`
+2. 匹配的请求到达 `server.js` 请求处理器
+3. 如果 `mock: false`（或尚未缓存）：
+   - 请求通过 `req.request()` 代理到真实服务器
+   - 响应被捕获并存储在 Whistle storage 中
+   - 响应流式传输给客户端
+4. 如果 `mock: true`：
+   - 直接从缓存返回存储的响应
+   - 如果设置了 `mockVersion`，则返回该版本的内容
+### 版本管理
+每个 mock 文件可以有多个版本：
+- 默认的 "source" 版本包含原始捕获的响应
+- 可以通过 UI 创建/编辑额外的命名版本
+- 激活的版本由 `mockVersion` 属性控制
+- 版本内容存储为 `version.{name}` 属性
+## Whistle 插件系统深度知识
+### 完整的插件钩子列表
+Whistle 支持以下钩子函数（来自 Whistle 源码 `lib/config.js`）：
+| 钩子名 | 说明 | mockbubu 使用 |
+|--------|------|---------------|
+| `server` | HTTP 请求拦截和响应 | ✅ 使用 |
+| `uiServer` | 插件 Web UI 服务 | ✅ 使用 |
+| `resRulesServer` | 在 Whistle UI 中定制样式 | ✅ 使用 |
+| `SNI` | SSL/TLS 证书动态加载 | ❌ 未使用 |
+| `AUTH` | 认证拦截 | ❌ 未使用 |
+| `TUNNEL_RULES` | 隧道规则 | ❌ 未使用 |
+| `REQ_STATS` | 请求统计上报 | ❌ 未使用 |
+| `RES_STATS` | 响应统计上报 | ❌ 未使用 |
+| `REQ_READ/REQ_WRITE` | 请求读写管道 | ❌ 未使用 |
+| `RES_READ/RES_WRITE` | 响应读写管道 | ❌ 未使用 |
+| `WS_REQ_READ/WRITE` | WebSocket 请求管道 | ❌ 未使用 |
+| `WS_RES_READ/WRITE` | WebSocket 响应管道 | ❌ 未使用 |
+| `TUNNEL_REQ/RES_*` | 隧道请求/响应管道 | ❌ 未使用 |
+### Storage API 底层实现
+从 Whistle 源码 (`lib/rules/storage.js`) 了解到的核心机制：
+**文件存储结构：**
+```
+~/.whistle/plugins/whistle.mockbubu/
+├── files/              # 实际文件内容
+│   ├── 0.filename1     # index.encodeURIComponent(name)
+│   ├── 1.filename2
+│   └── ...
+├── properties          # 元数据 JSON 文件
+├── .backup/            # 自动备份目录
+│   ├── files/
+│   └── properties
+└── .recycle_bin/       # 回收站（删除的文件）
+```
+**核心特性：**
+1. **文件名编码**：使用 `index + '.' + encodeURIComponent(name)`，最大长度 254 字符
+2. **双写备份**：每次写入同时写 `files/` 和 `.backup/`，保证数据安全
+3. **崩溃恢复**：启动时自动从 `.backup/` 恢复损坏的文件
+4. **Properties**：JSON 格式存储所有元数据，也有备份机制
+5. **回收站**：删除的文件进入 `.recycle_bin/`，可恢复
+**我们的使用方式完全符合 Whistle 的设计理念！**
+### 插件生命周期
+```
+1. 扫描阶段
+   - getPluginsSync() 扫描 node_modules/ 和全局目录
+   - 查找 whistle.* 开头的包
+2. 解析阶段
+   - 读取 package.json
+   - 解析 whistleConfig 配置
+   - 提取 rules.txt、_rules.txt、resRules.txt
+3. 加载阶段
+   - 通过 pfork 启动子进程
+   - 加载插件的 index.js
+   - 启动各个钩子服务（server, uiServer 等）
+4. 运行阶段
+   - 定时检查更新（每 6 秒）
+   - 版本检查（每 2 小时）
+   - 规则更新触发重新解析
+5. 卸载阶段
+   - 停止子进程
+   - 清理端口占用
+   - 更新规则列表
+```
+### 请求处理关键 API
+**req 对象扩展属性：**
+- `req.originalReq.{id, method, url, headers, clientIp, ...}` - 原始请求信息
+- `req.originalRes.{statusCode, headers, ...}` - 原始响应信息
+- `req.localStorage` - 访问 Storage API
+- `req.Storage` - Storage 类构造器
+- `req.sharedStorage` - 跨插件共享存储
+- `req.clientIp` - 客户端 IP
+- `req.fullUrl` - 完整 URL
+- `req.isHttps` - 是否 HTTPS
+- `req.fromComposer` - 是否来自 Composer
+**核心方法：**
+- `req.request(options, callback)` - 发起新的 HTTP 请求
+- `req.passThrough()` - 透传请求（不拦截）
+- `req.getSession(callback)` - 获取完整会话信息（包括响应）
+- `req.getReqSession(callback)` - 仅获取请求信息
+### Whistle 规则传递
+当规则匹配 `pattern mockbubu://pathname` 时，Whistle 通过 HTTP headers 传递信息：
+- `x-whistle-rule-value` - 规则值（pathname/href/pattern）
+- `x-whistle-full-url` - 完整 URL
+- `x-whistle-real-url` - 真实 URL（可能被重定向）
+- `x-whistle-method` - HTTP 方法
+- `x-whistle-client-ip` - 客户端 IP
+- `x-whistle-req-id` - 请求唯一 ID
+### 最佳实践总结
+基于 Whistle 源码学习，mockbubu 的设计符合以下最佳实践：
+✅ **符合的设计：**
+1. 使用 `req.localStorage` 进行数据持久化
+2. 使用 `req.passThrough()` 透传不需要 mock 的请求
+3. 正确处理压缩响应（gzip/deflate/br）
+4. 使用 Properties 存储元数据
+5. 文件名通过 URL 生成（pathname/href/pattern）
+⚠️ **可以优化的点：**
+1. 考虑使用 `REQ_STATS/RES_STATS` 钩子收集统计数据
+2. 可以使用 `sharedStorage` 实现跨插件数据共享
+3. 考虑添加 `AUTH` 钩子实现访问控制
+4. 使用 Whistle 的回收站机制（目前我们直接删除）
+## 代码风格
+- **后端**: ESLint Standard 风格，2 空格缩进，单引号，无分号
+- **前端**: Vue/ESLint Standard 风格
+- 提交前使用 `npm run lint:fix` 自动格式化代码