whistle.mockbubu 1.0.0-dev.4 → 2.0.0-beta.0

package/rules.txt

@@ -1,2 +1,2 @@
 # 默认会经历所有server
-# * mockbubu://
+# *.shein.com mockbubu://

package//346/212/200/346/234/257/346/226/271/346/241/210.md

@@ -0,0 +1,452 @@
+【技术需求】Whistle Mock 插件 - whistle.mockbubu
+
+## 一、背景（技术需求必填）
+
+### 需求背景分析
+在前后端分离的开发模式下，前端开发经常需要等待后端接口开发完成才能进行联调测试，这严重影响了开发效率。同时，测试环境不稳定、接口响应数据不符合预期等问题也频繁出现。
+
+### 业务现状介绍
+- 前端开发依赖后端接口完成后才能进行功能开发和测试
+- 测试环境接口不稳定，影响开发和测试效率
+- 缺乏便捷的接口数据 mock 工具，手动修改响应数据效率低
+- 多人协作时，mock 数据管理混乱，缺乏环境隔离
+
+### 业务痛点分析
+1. **开发效率低**：等待后端接口开发完成，前端无法独立开发
+2. **测试困难**：难以模拟各种边界情况和异常场景
+3. **环境污染**：测试数据相互干扰，缺乏环境隔离
+4. **数据管理**：mock 数据分散，难以管理和版本控制
+5. **协作困难**：团队成员之间无法共享和复用 mock 数据
+
+### 方案设计目标介绍
+开发一个基于 Whistle 的 API mock 插件，实现：
+- 自动捕获真实 API 响应并支持编辑
+- 灵活的 mock 开关，支持一键切换真实/模拟数据
+- 完全隔离的多环境管理（分组模式：可自行管理开发、测试、预发或不同需求和复现bug等场景的mock数据）
+- 版本管理功能，支持响应数据的多版本切换
+- 直观的 Web UI，提升操作体验
+
+## 二、价值评估（技术需求必填）
+
+### 开发效率提升
+- **并行开发**：前后端完全解耦，前端可基于接口约定独立开发，预计提升 30% 开发效率
+- **快速调试**：一键切换真实/模拟数据，无需修改代码，节省 50% 调试时间
+- **多场景测试**：轻松模拟各种边界情况和异常场景，覆盖率提升 40%
+
+### 团队协作优化
+- **环境隔离**：完全隔离的多环境管理，避免测试数据相互污染
+- **数据复用**：版本管理支持，团队成员可共享和复用 mock 数据
+- **降低沟通成本**：减少因环境问题导致的沟通成本约 20%
+
+### 用户体验改进
+- **直观 UI**：基于 Vue + Element UI 的现代化界面，学习成本低
+- **实时预览**：修改 mock 数据后立即生效，无需重启
+- **智能提示**：JSON 编辑器支持语法高亮和错误提示
+
+### 长期价值
+- **可维护性**：插件化架构，易于扩展和维护
+- **标准化**：统一团队的 mock 方案，形成最佳实践
+- **成本节约**：开源方案，无需购买商业 mock 平台
+
+## 三、技术方案（必填）
+
+### 3.1 技术方案调研
+
+#### 方案前期调研
+调研了市面上主流的 mock 方案：
+1. **Mock.js**：纯前端 mock，无法拦截真实网络请求
+2. **Yapi / Rap2**：需要独立部署后端服务，维护成本高
+3. **Charles / Fiddler**：功能强大但操作复杂，学习成本高
+4. **Whistle 插件**：轻量级，与现有工具链完美集成
+
+#### 方案选型、优缺点对比
+| 方案 | 优点 | 缺点 | 评分 |
+|------|------|------|------|
+| Mock.js | 轻量，易用 | 无法拦截真实请求，功能有限 | 6/10 |
+| Yapi/Rap2 | 功能完善，支持团队协作 | 需要独立部署，维护成本高 | 7/10 |
+| Charles/Fiddler | 功能强大，成熟稳定 | 操作复杂，学习成本高 | 7/10 |
+| **Whistle 插件** | 轻量，易集成，开发友好 | 需要开发，初期投入 | **9/10** |
+
+#### 方案调研结论
+选择基于 Whistle 开发插件，原因：
+- 团队已广泛使用 Whistle，无额外学习成本
+- 插件化架构，易于定制和扩展
+- 轻量级，无需独立部署后端服务
+- 社区活跃，生态完善
+
+### 3.2 技术方案整体设计（必填）
+
+#### 整体架构
+```
+┌─────────────────────────────────────────────────────┐
+│                  Whistle (代理层)                    │
+├─────────────────────────────────────────────────────┤
+│              whistle.mockbubu 插件                   │
+├──────────────────┬──────────────────────────────────┤
+│   后端 (Node.js) │       前端 (Vue 2.7)              │
+│   - Koa Server   │   - MockContainer (主容器)        │
+│   - 请求拦截器   │   - RequestList (列表)            │
+│   - Storage API  │   - RequestDetail (详情)          │
+│   - 分组管理器   │   - ResponsePanel (编辑器)        │
+│   - 版本管理     │   - GroupManager (分组管理)       │
+└──────────────────┴──────────────────────────────────┘
+          │                          │
+          ↓                          ↓
+    Whistle Storage          Element UI + JsonEditor
+   (本地文件存储)              (UI 组件库)
+```
+
+#### 整体流程
+1. **请求捕获**：Whistle 拦截匹配规则的 HTTP 请求
+2. **数据存储**：插件捕获真实响应并存储到本地
+3. **Mock 开关**：用户通过 Web UI 控制是否启用 mock
+4. **数据编辑**：Web UI 提供 JSON 编辑器修改响应数据
+5. **版本管理**：支持创建多个版本并灵活切换
+6. **环境隔离**：完全隔离的分组管理，避免数据污染
+
+#### 业务流程图
+
+```mermaid
+flowchart TD
+    Start([用户发起 HTTP 请求]) --> Whistle{Whistle 规则匹配}
+    Whistle -->|匹配 mockbubu://| Plugin[whistle.mockbubu 插件]
+    Whistle -->|不匹配| PassThrough[直接透传]
+
+    Plugin --> CheckMock{检查 Mock 开关}
+
+    CheckMock -->|Mock: ON + 有缓存| ReturnMock[返回 Mock 数据]
+    CheckMock -->|Mock: ON + 无缓存| CaptureFirst[先捕获真实数据]
+    CheckMock -->|Mock: OFF| CheckCache{有缓存?}
+
+    CheckCache -->|有缓存| PassThrough2[直接透传]
+    CheckCache -->|无缓存| Capture[捕获真实响应]
+
+    CaptureFirst --> RealRequest1[请求真实服务器]
+    Capture --> RealRequest2[请求真实服务器]
+
+    RealRequest1 --> SaveData1[存储响应数据]
+    RealRequest2 --> SaveData2[存储响应数据]
+
+    SaveData1 --> ReturnReal1[返回真实响应]
+    SaveData2 --> ReturnReal2[返回真实响应]
+
+    ReturnMock --> End([返回给客户端])
+    ReturnReal1 --> End
+    ReturnReal2 --> End
+    PassThrough --> End
+    PassThrough2 --> End
+
+    style Plugin fill:#e1f5ff
+    style ReturnMock fill:#b7eb8f
+    style Capture fill:#ffe58f
+    style SaveData1 fill:#ffe58f
+    style SaveData2 fill:#ffe58f
+```
+
+#### 请求拦截时序图
+
+```mermaid
+sequenceDiagram
+    participant Client as 浏览器/客户端
+    participant Whistle as Whistle 代理
+    participant Plugin as mockbubu 插件
+    participant Storage as Whistle Storage
+    participant Server as 真实服务器
+
+    Client->>Whistle: 1. 发起 HTTP 请求
+    Whistle->>Whistle: 2. 匹配规则 (mockbubu://)
+    Whistle->>Plugin: 3. 转发到插件处理
+
+    Plugin->>Storage: 4. 读取文件配置 (mock 开关)
+    Storage-->>Plugin: 5. 返回配置信息
+
+    alt Mock: ON 且有缓存
+        Plugin->>Storage: 6a. 读取缓存数据
+        Storage-->>Plugin: 7a. 返回 Mock 数据
+        Plugin-->>Client: 8a. 返回 Mock 响应
+    else Mock: ON 但无缓存
+        Plugin->>Server: 6b. 请求真实服务器
+        Server-->>Plugin: 7b. 返回真实响应
+        Plugin->>Storage: 8b. 存储响应数据
+        Plugin-->>Client: 9b. 返回真实响应
+    else Mock: OFF 且无缓存
+        Plugin->>Server: 6c. 请求真实服务器
+        Server-->>Plugin: 7c. 返回真实响应
+        Plugin->>Storage: 8c. 存储响应数据 (首次捕获)
+        Plugin-->>Client: 9c. 返回真实响应
+    else Mock: OFF 且有缓存
+        Plugin->>Whistle: 6d. 透传请求
+        Whistle->>Server: 7d. 请求真实服务器
+        Server-->>Whistle: 8d. 返回真实响应
+        Whistle-->>Client: 9d. 返回真实响应
+    end
+```
+
+#### 用户操作流程图
+
+```mermaid
+flowchart LR
+    subgraph 初始配置
+        A1[配置 Whistle 规则] --> A2[启动 Whistle]
+        A2 --> A3[打开插件 Web UI]
+    end
+
+    subgraph 首次捕获
+        B1[触发 HTTP 请求] --> B2[插件自动捕获]
+        B2 --> B3[在列表中显示]
+    end
+
+    subgraph 数据管理
+        C1[点击文件查看] --> C2[编辑 Response 数据]
+        C2 --> C3{保存类型}
+        C3 -->|覆盖原版本| C4[更新 source 版本]
+        C3 -->|创建新版本| C5[创建 v1/v2 等版本]
+        C5 --> C6[版本切换]
+    end
+
+    subgraph Mock控制
+        D1[开启 Mock 开关] --> D2[再次发起请求]
+        D2 --> D3[返回 Mock 数据]
+        D3 --> D4{需要调试?}
+        D4 -->|是| D5[关闭 Mock 看真实数据]
+        D4 -->|否| D6[继续开发]
+    end
+
+    subgraph 环境管理
+        E1[创建新分组] --> E2[切换分组]
+        E2 --> E3[独立的 Mock 数据]
+        E3 --> E4[多环境隔离]
+    end
+
+    A3 --> B1
+    B3 --> C1
+    C6 --> D1
+    D6 --> E1
+    D5 --> B1
+
+    style A1 fill:#e6f7ff
+    style B2 fill:#fff7e6
+    style C2 fill:#f6ffed
+    style D1 fill:#fff1f0
+    style E3 fill:#f9f0ff
+```
+
+#### 数据流图
+
+```mermaid
+flowchart TB
+    subgraph 用户层
+        UI[Web UI 界面]
+    end
+
+    subgraph 应用层
+        API[RESTful API]
+        GM[Group Manager<br/>分组管理器]
+        VM[Version Manager<br/>版本管理器]
+    end
+
+    subgraph 服务层
+        Interceptor[Request Interceptor<br/>请求拦截器]
+        Utils[Utils<br/>工具函数]
+    end
+
+    subgraph 存储层
+        Storage[(Whistle Storage<br/>本地文件存储)]
+        Files["files/{groupId}/{filename}<br/>物理文件"]
+        Props[properties<br/>元数据配置]
+    end
+
+    subgraph 外部
+        Browser[浏览器请求]
+        RealServer[真实服务器]
+    end
+
+    UI -->|用户操作| API
+    API --> GM
+    API --> VM
+    GM --> Utils
+    VM --> Utils
+    Utils --> Storage
+    Storage --> Files
+    Storage --> Props
+
+    Browser --> Interceptor
+    Interceptor --> Utils
+    Interceptor --> RealServer
+    RealServer -->|真实响应| Interceptor
+    Interceptor -->|Mock/真实响应| Browser
+
+    style UI fill:#e6f7ff
+    style API fill:#fff7e6
+    style GM fill:#f6ffed
+    style VM fill:#f6ffed
+    style Interceptor fill:#fff1f0
+    style Storage fill:#f9f0ff
+    style Files fill:#ffd6e7
+    style Props fill:#ffd6e7
+```
+
+### 3.3 技术方案详细设计
+
+#### 关键技术栈
+**后端**：
+- Node.js 18+ + Koa 2.7
+- Whistle Storage API（本地文件存储）
+- Koa-Router（路由）
+- Koa-Bodyparser（请求体解析）
+
+**前端**：
+- Vue 2.7 + Composition API
+- Element UI（UI 组件库）
+- jsoneditor（JSON 编辑器）
+- Vue CLI 5（构建工具）
+
+#### 关键设计点
+
+**1. 完全隔离架构（Phase 1 已完成）**
+- 文件存储路径：`files/{groupId}/{filename}`
+- 每个组独立的物理文件空间
+- 组配置独立管理：`group.{groupId}.file.{filename}`
+- 删除文件时无需检查其他组引用
+
+**2. 多版本管理**
+- 默认 `source` 版本（原始捕获的响应）
+- 支持创建自定义版本（如 v1、v2、测试版等）
+- 版本切换无需重启，实时生效
+- 版本元数据：创建时间、更新时间、描述
+
+**3. 智能捕获逻辑**
+```
+if (mock && hasCache) {
+  // 返回 mock 数据
+} else if (mock && !hasCache) {
+  // 先捕获真实数据
+} else {
+  // mock:false，透传或捕获
+}
+```
+
+**4. UI 交互优化**
+- Response Tab 默认选中
+- localStorage 记住用户的 tab 选择
+- 列表高亮状态同步（刷新、切换、删除场景）
+- 表格 key 强制重渲染，解决样式残留
+
+#### 异常边界
+1. **文件锁定机制**：防止误删重要 mock 数据
+2. **批量操作确认**：批量删除前二次确认
+3. **JSON 格式校验**：编辑器实时校验 JSON 语法
+4. **压缩响应处理**：自动解压 gzip/deflate/br
+5. **首次捕获检测**：使用 `hasProperty` 准确判断
+
+#### 统计上报、效果监控评估
+- 插件使用量：通过 npm 下载量统计
+- 用户反馈：GitHub Issues 收集问题和建议
+- 性能监控：日志记录关键操作耗时
+
+#### 日志打点
+- 请求捕获日志：`[mockbubu] ✅ 已捕获 | File: xxx`
+- Mock 返回日志：`[mockbubu] 🔄 返回 Mock 数据 | File: xxx`
+- 错误日志：`[mockbubu] ❌ 错误 | xxx`
+- 调试日志：控制台输出关键状态
+
+#### 方案阶段计划
+
+**Phase 0（已完成）**：基础功能
+- ✅ 请求捕获和 mock 开关
+- ✅ Web UI 基础页面
+- ✅ JSON 编辑器集成
+
+**Phase 1（已完成）**：完全隔离架构
+- ✅ 组独立文件存储
+- ✅ 多版本管理
+- ✅ UI 交互优化
+- ✅ 发布 npm v2.0.0
+
+**Phase 2（计划中）**：存储管理
+- 🔄 存储统计信息
+- 🔄 孤儿文件清理
+- 🔄 未使用文件清理
+- 🔄 存储空间优化
+
+**Phase 3（规划中）**：高级功能
+- 📋 导入/导出功能
+- 📋 团队协作功能
+- 📋 Mock 数据模板库
+- 📋 智能推荐功能
+
+#### 具体开发事项拆分
+1. **后端开发**（5 天）
+   - Koa 服务器搭建（0.5 天）
+   - 请求拦截逻辑（1 天）
+   - Storage API 封装（1 天）
+   - 分组管理器（1.5 天）
+   - 版本管理器（1 天）
+
+2. **前端开发**（5 天）
+   - Vue 项目搭建（0.5 天）
+   - 主容器和路由（0.5 天）
+   - 列表和详情组件（1.5 天）
+   - JSON 编辑器集成（1 天）
+   - 分组管理界面（1.5 天）
+
+3. **联调测试**（2 天）
+   - 基础功能测试（1 天）
+   - 边界情况测试（1 天）
+
+#### 工作量评估
+- 总工作量：**12 人天**
+- 开发人员：1 名全栈工程师
+- 开发周期：**2.5 周**（包含设计、开发、测试）
+
+#### 联调排期计划
+无需与后端联调，插件独立运行。测试计划：
+- 单元测试：核心工具函数测试
+- 集成测试：完整流程测试
+- 验收测试：实际项目中使用验证
+
+#### 资源依赖
+- ✅ Whistle 2.9.84+（已安装）
+- ✅ Node.js 18+（已安装）
+- ✅ Element UI 2.x（已集成）
+- ✅ jsoneditor 库（已集成）
+
+#### 测试验证标准
+1. **功能完整性**：所有需求点均已实现
+2. **稳定性**：无崩溃、无数据丢失
+3. **性能**：响应时间 < 100ms
+4. **兼容性**：支持主流浏览器（Chrome、Edge、Firefox）
+5. **用户体验**：操作流畅，UI 友好
+
+#### 发布计划
+- ✅ **v1.x.x**：基础功能发布
+- ✅ **v2.0.0**：完全隔离架构 + UI 优化（2025-10-22 已发布）
+- 🔄 **v2.1.0**：存储管理功能（计划中）
+- 📋 **v3.0.0**：团队协作功能（规划中）
+
+---
+
+## 附录
+
+### 项目信息
+- **项目名称**：whistle.mockbubu
+- **npm 包**：https://www.npmjs.com/package/whistle.mockbubu
+- **版本**：2.0.0
+- **License**：MIT
+- **作者**：Zac Chen <zacchen@shein.com>
+
+### 安装使用
+```bash
+# 全局安装
+npm install whistle.mockbubu -g
+
+# 或使用 whistle 命令
+w2 install whistle.mockbubu
+```
+
+### 核心指标（截至 v2.0.0）
+- 代码行数：~3000 行（前端 + 后端）
+- 文件数量：32 个
+- 打包大小：3.0 MB
+- 解压大小：9.8 MB
+- 测试覆盖率：33 个核心测试用例

package//346/265/213/350/257/225/346/215/225/350/216/267/345/212/237/350/203/275/346/255/245/351/252/244.md

@@ -0,0 +1,145 @@
+# mockbubu 捕获功能测试步骤
+
+## 当前状态
+- ✅ Whistle 运行在端口 8899
+- ✅ mockbubu 插件已加载
+- ✅ 规则配置: `*.shein.com mockbubu://`
+- ⚠️ **需要浏览器配置代理才能测试**
+
+## 测试步骤
+
+### 方法 1: Chrome 浏览器测试 (推荐)
+
+1. **安装 SwitchyOmega 插件** (如果还没安装)
+   - Chrome 应用商店搜索 "Proxy SwitchyOmega"
+   - 或者访问: https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif
+
+2. **配置代理**
+   - 打开 SwitchyOmega 设置
+   - 新建情景模式,选择 "代理服务器"
+   - 配置:
+     - 代理协议: HTTP
+     - 代理服务器: 127.0.0.1
+     - 代理端口: 8899
+   - 保存并启用该情景模式
+
+3. **访问 SHEIN 网站触发 JSON API**
+   - 打开: https://m.shein.com/us/
+   - 或者: https://www.shein.com/
+   - 网站会自动发送很多 JSON API 请求
+
+4. **查看捕获结果**
+   - 打开: http://127.0.0.1:8899/whistle.mockbubu/
+   - 应该能看到捕获的请求列表
+
+### 方法 2: 系统代理测试
+
+1. **配置系统代理** (macOS)
+   ```bash
+   # 打开系统偏好设置 > 网络 > 高级 > 代理
+   # 勾选 "网页代理(HTTP)"
+   # 服务器: 127.0.0.1
+   # 端口: 8899
+   # 勾选 "安全网页代理(HTTPS)"
+   # 服务器: 127.0.0.1
+   # 端口: 8899
+   ```
+
+2. **访问网站测试**
+   - 用任何浏览器打开: https://m.shein.com/
+   - 网站会发送 JSON API 请求
+
+3. **查看捕获结果**
+   - 打开: http://127.0.0.1:8899/whistle.mockbubu/
+
+### 方法 3: curl 测试 (命令行)
+
+由于 `m.shein.com/us/api/xxx` 这些测试端点不存在,返回的都是 HTML 页面,所以 curl 测试会失败。
+
+**需要真实的 API 端点才能测试!**
+
+## 验证方法
+
+### 1. 检查文件是否被捕获
+```bash
+# 查看 default 组的文件数量
+find ~/.WhistleAppData/.whistle/.plugins/whistle.mockbubu/groups/default/files -type d -mindepth 1 -maxdepth 1 | wc -l
+
+# 查看 index.json
+cat ~/.WhistleAppData/.whistle/.plugins/whistle.mockbubu/groups/default/index.json
+```
+
+### 2. 查看日志
+```bash
+# 查看 Whistle 主日志
+tail -50 ~/.WhistleAppData/whistle.log
+
+# 查找 mockbubu 相关日志
+tail -100 ~/.WhistleAppData/whistle.log | grep mockbubu
+```
+
+### 3. 查看 UI
+打开浏览器访问:
+- Whistle 主界面: http://127.0.0.1:8899/
+- mockbubu 插件界面: http://127.0.0.1:8899/whistle.mockbubu/
+
+## 预期结果
+
+当配置正确并访问 shein.com 后,你应该看到:
+
+1. **文件被创建**
+   ```bash
+   $ ls ~/.WhistleAppData/.whistle/.plugins/whistle.mockbubu/groups/default/files/
+   0a3f2e8b/  1b4c5d9f/  2e6a7f0c/  # 每个目录对应一个捕获的请求
+   ```
+
+2. **index.json 有数据**
+   ```json
+   {
+     "version": "3.0.0",
+     "files": [
+       {
+         "id": "0a3f2e8b",
+         "url": "https://m.shein.com/us/api/user/info",
+         "method": "GET",
+         "status": 200
+       }
+     ]
+   }
+   ```
+
+3. **UI 显示列表**
+   - 打开 http://127.0.0.1:8899/whistle.mockbubu/
+   - 能看到捕获的请求列表
+   - 点击可以查看请求详情
+
+## 常见问题
+
+### Q: 浏览器访问了网站,但没有捕获到请求?
+
+**A:** 检查以下几点:
+1. 浏览器是否配置了代理到 127.0.0.1:8899?
+2. 代理是否启用?
+3. 访问的是否是 HTTPS 网站?(需要安装 Whistle 证书)
+4. Whistle 规则是否启用?
+
+### Q: 如何安装 Whistle 证书?
+
+**A:**
+1. 配置代理后,访问: http://local.whistlejs.com/
+2. 点击 HTTPS
+3. 下载根证书并安装到系统
+
+### Q: curl 测试为什么不工作?
+
+**A:** 因为测试的 API 端点不存在,返回的是 HTML 而不是 JSON。mockbubu 只捕获 JSON 响应(`Content-Type: application/json` 或 `Accept: application/json`请求)。
+
+需要访问真实的网站来触发真实的 API 请求才能测试。
+
+## 下一步
+
+测试通过后,可以继续:
+1. 测试 Mock 功能(开启 mock 开关,验证是否返回缓存数据)
+2. 测试版本管理功能
+3. 测试分组功能
+4. 进行完整的端到端测试