whistle.mock-plugins 1.0.0

package/API.md

@@ -0,0 +1,247 @@
+# whistle.mock-plugin API 文档
+
+本文档描述了 whistle.mock-plugin 插件的 API 接口和数据模型。
+
+## 数据模型
+
+### 功能模块 (Feature)
+
+功能模块是接口的分组，用于组织和管理相关的接口。
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| id | string | 功能模块唯一标识符 |
+| name | string | 功能模块名称 |
+| description | string | 功能模块描述 |
+| interfaceCount | number | 该功能模块下的接口数量 |
+| active | boolean | 功能模块是否启用 |
+| createdAt | string | 创建时间，ISO 字符串格式 |
+| updatedAt | string | 最后更新时间，ISO 字符串格式 |
+
+### 接口 (Interface)
+
+接口定义了匹配规则和响应内容，用于模拟 API 响应。
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| id | string | 接口唯一标识符 |
+| featureId | string | 所属功能模块 ID |
+| name | string | 接口名称 |
+| urlPattern | string | URL 匹配规则，支持精确匹配、通配符和正则表达式 |
+| proxyType | string | 代理类型，可选值: 'response'(数据模板), 'redirect'(URL重定向), 'file'(文件代理) |
+| responseContent | string | 响应内容，使用 Mock.js 语法 |
+| targetUrl | string | 重定向目标 URL，仅在 proxyType='redirect' 时有效 |
+| filePath | string | 文件路径，仅在 proxyType='file' 时有效 |
+| httpStatus | number | HTTP 状态码 |
+| responseDelay | number | 响应延迟，单位毫秒 |
+| httpMethod | string | HTTP 方法，可选值: 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'ALL' |
+| active | boolean | 接口是否启用 |
+| contentType | string | 响应内容类型 |
+| headers | object | 自定义响应头 |
+| createdAt | string | 创建时间，ISO 字符串格式 |
+| updatedAt | string | 最后更新时间，ISO 字符串格式 |
+
+### API 响应 (ApiResponse)
+
+所有 API 接口的标准响应格式。
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| code | number | 状态码，0 表示成功，其他值表示错误 |
+| message | string | 状态消息 |
+| data | any | 响应数据，具体结构根据接口而定 |
+
+## API 接口
+
+### 功能模块
+
+#### 获取所有功能模块
+
+```
+GET /cgi-bin/features
+```
+
+请求参数：无
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "成功",
+  "data": [
+    {
+      "id": "1",
+      "name": "用户管理",
+      "description": "用户相关接口",
+      "interfaceCount": 3,
+      "active": true,
+      "createdAt": "2023-01-01T00:00:00.000Z",
+      "updatedAt": "2023-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+#### 获取指定功能模块的接口列表
+
+```
+GET /cgi-bin/interfaces?featureId={featureId}
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| featureId | string | 是 | 功能模块 ID |
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "成功",
+  "data": [
+    {
+      "id": "1",
+      "featureId": "1",
+      "name": "获取用户信息",
+      "urlPattern": "/api/users/*",
+      "proxyType": "response",
+      "responseContent": "{\"code\":0,\"data\":{\"id\":1,\"name\":\"test\"}}",
+      "httpStatus": 200,
+      "contentType": "application/json; charset=utf-8",
+      "active": true
+    }
+  ]
+}
+```
+
+### 接口
+
+#### 创建接口
+
+```
+POST /cgi-bin/interfaces
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| name | string | 是 | 接口名称 |
+| featureId | string | 是 | 功能模块 ID |
+| urlPattern | string | 是 | URL 匹配规则 |
+| proxyType | string | 否 | 代理类型，默认 'response' |
+| responseContent | string | 否 | 响应内容 |
+| httpStatus | number | 否 | HTTP 状态码，默认 200 |
+| contentType | string | 否 | 响应内容类型 |
+| active | boolean | 否 | 是否启用，默认 true |
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "接口创建成功",
+  "data": {
+    "id": "1",
+    "featureId": "1",
+    "name": "获取用户信息",
+    "urlPattern": "/api/users/*",
+    "proxyType": "response",
+    "responseContent": "{\"code\":0,\"data\":{\"id\":1,\"name\":\"test\"}}",
+    "httpStatus": 200,
+    "contentType": "application/json; charset=utf-8",
+    "active": true
+  }
+}
+```
+
+#### 更新接口
+
+```
+PUT /cgi-bin/interfaces?id={id}
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| id | string | 是 | 接口 ID (URL参数) |
+| name | string | 否 | 接口名称 |
+| urlPattern | string | 否 | URL 匹配规则 |
+| proxyType | string | 否 | 代理类型 |
+| responseContent | string | 否 | 响应内容 |
+| httpStatus | number | 否 | HTTP 状态码 |
+| contentType | string | 否 | 响应内容类型 |
+| active | boolean | 否 | 是否启用 |
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "接口更新成功",
+  "data": {
+    "id": "1",
+    "featureId": "1",
+    "name": "获取用户信息",
+    "urlPattern": "/api/users/*",
+    "proxyType": "response",
+    "responseContent": "{\"code\":0,\"data\":{\"id\":1,\"name\":\"updated\"}}",
+    "httpStatus": 200,
+    "contentType": "application/json; charset=utf-8",
+    "active": true
+  }
+}
+```
+
+#### 删除接口
+
+```
+DELETE /cgi-bin/interfaces?id={id}
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| id | string | 是 | 接口 ID (URL参数) |
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "接口删除成功",
+  "data": null
+}
+```
+
+#### 测试接口
+
+```
+POST /cgi-bin/test-interface
+```
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| url | string | 是 | 测试 URL |
+| interfaceId | string | 是 | 接口 ID |
+
+响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "成功",
+  "data": {
+    "statusCode": 200,
+    "contentType": "application/json; charset=utf-8",
+    "responseBody": "{\"code\":0,\"data\":{\"id\":1,\"name\":\"test\"}}"
+  }
+}
+``` 

package/README.md

@@ -0,0 +1,91 @@
+# Whistle Mock Plugin
+
+一个用于Whistle的mock数据插件，帮助前端开发者管理和模拟API接口响应。
+
+## 核心功能
+
+### 1. 功能模块管理
+
+- **创建功能模块**：用户可以创建多个功能模块，每个模块代表一组相关的API接口
+- **启用/禁用功能模块**：整体控制一组接口的启用状态
+- **管理功能模块**：编辑、删除功能模块及其描述信息
+
+### 2. 接口代理配置
+
+在每个功能模块下，用户可以添加多个接口代理配置，支持以下代理方式：
+
+- **URL重定向**：将请求重定向到另一个URL地址
+- **本地文件代理**：返回本地文件的内容作为响应
+- **响应内容直接配置**：直接编辑JSON、HTML等响应内容
+
+### 3. 代理规则控制
+
+- **每个接口可独立启用/禁用**：精细控制每个接口的代理状态
+- **匹配规则配置**：支持精确匹配、通配符、正则表达式等多种匹配方式
+- **请求方法过滤**：可限定特定HTTP方法(GET, POST等)的请求被代理
+
+### 4. 高级功能
+
+- **响应延迟模拟**：模拟网络延迟，可针对接口设置响应时间
+- **状态码与响应头配置**：自定义HTTP状态码和响应头
+- **请求日志记录**：记录被代理的请求，便于调试和回溯
+
+## 使用场景
+
+1. **前后端分离开发**：前端开发不依赖后端接口进度
+2. **复杂场景测试**：模拟各种API响应状态和错误情况
+3. **演示环境搭建**：快速构建演示环境，无需部署完整后端
+4. **接口联调**：在本地环境联调多个微服务接口
+
+## 项目结构
+
+```
+whistle.mock-plugin/
+├── app/                  # 插件服务端代码
+│   ├── index.js          # 插件入口文件
+│   └── public/           # 插件UI静态资源
+├── ui/                   # 插件UI源代码
+│   ├── src/              # React源代码
+│   ├── package.json      # UI依赖配置
+│   └── webpack.config.js # 构建配置
+├── package.json          # 插件依赖配置
+└── README.md             # 项目说明文档
+```
+
+## 页面结构
+
+### 1. 首页/概览
+
+- 显示插件使用统计信息
+- 快速入门指南和使用提示
+- 最近活动记录
+
+### 2. 功能模块管理页面
+
+- 功能模块列表展示
+- 添加/编辑/删除功能模块
+- 功能模块启用/禁用控制
+- 每个功能模块的接口数量统计
+
+### 3. 接口管理页面
+
+- 特定功能模块下的接口列表
+- 添加/编辑/删除接口配置
+- 接口启用/禁用控制
+- 接口详细配置：
+  - URL匹配规则
+  - 代理方式选择(URL重定向/本地文件/直接响应)
+  - 响应配置(状态码、头信息、延迟)
+
+### 4. 系统设置页面
+
+- 全局插件设置
+- 日志记录设置
+- 默认响应行为配置
+
+## 技术实现
+
+- 前端：React框架构建UI界面
+- 构建：使用Webpack打包前端资源
+- 插件通信：利用Whistle插件API与主程序通信
+- 数据存储：使用本地文件系统存储配置信息 

package/app/cgi-bin/features.js

@@ -0,0 +1,285 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+module.exports = function(req, res) {
+  const dataDir = this.dataDir;
+  const featuresFile = path.join(dataDir, 'features.json');
+  const interfacesFile = path.join(dataDir, 'interfaces.json');
+  
+  try {
+    // 确保配置文件存在并包含有效结构
+    if (!fs.existsSync(featuresFile)) {
+      fs.writeJsonSync(featuresFile, { features: [] }, { spaces: 2 });
+    } else {
+      // 读取文件验证结构
+      try {
+        const fileData = fs.readJsonSync(featuresFile);
+        if (!fileData || !fileData.features) {
+          // 如果文件存在但结构无效，重新初始化
+          fs.writeJsonSync(featuresFile, { features: [] }, { spaces: 2 });
+          console.log('修复了损坏的features文件结构');
+        }
+      } catch (e) {
+        // JSON解析错误时重新初始化文件
+        fs.writeJsonSync(featuresFile, { features: [] }, { spaces: 2 });
+        console.log('修复了无法解析的features文件');
+      }
+    }
+    
+    // 处理GET请求 - 获取所有功能模块
+    if (req.method === 'GET') {
+      let featuresData;
+      try {
+        featuresData = fs.readJsonSync(featuresFile);
+        if (!featuresData.features) {
+          featuresData.features = [];
+        }
+      } catch (err) {
+        // 读取出错时返回空数组
+        console.error('读取功能列表错误:', err);
+        featuresData = { features: [] };
+      }
+      
+      // 计算每个功能模块的接口数量
+      if (fs.existsSync(interfacesFile)) {
+        try {
+          const interfacesData = fs.readJsonSync(interfacesFile);
+          const interfaces = interfacesData.interfaces || [];
+          
+          // 统计接口数量
+          for (const feature of featuresData.features) {
+            feature.interfaceCount = interfaces.filter(item => item.featureId === feature.id).length;
+          }
+        } catch (err) {
+          console.error('读取接口列表错误:', err);
+          // 读取接口出错时不影响功能列表返回
+        }
+      }
+      
+      return res.json({
+        code: 0,
+        message: '成功',
+        data: featuresData.features
+      });
+    }
+    
+    // 处理POST请求 - 添加或更新功能模块
+    if (req.method === 'POST') {
+      const featureData = req.body;
+      let featuresData;
+      
+      try {
+        featuresData = fs.readJsonSync(featuresFile);
+        if (!featuresData.features) {
+          featuresData = { features: [] };
+        }
+      } catch (err) {
+        // 读取出错时初始化
+        console.error('读取功能列表错误:', err);
+        featuresData = { features: [] };
+      }
+      
+      // 参数验证
+      if (!featureData.name) {
+        return res.status(400).json({
+          code: 400,
+          message: '功能名称不能为空',
+          data: null
+        });
+      }
+      
+      // 如果有ID则更新，否则创建新功能
+      if (featureData.id) {
+        // 更新现有功能
+        const index = featuresData.features.findIndex(item => item.id === featureData.id);
+        
+        if (index === -1) {
+          return res.status(404).json({
+            code: 404,
+            message: '功能模块不存在',
+            data: null
+          });
+        }
+        
+        // 更新功能
+        featuresData.features[index] = {
+          ...featuresData.features[index],
+          name: featureData.name,
+          description: featureData.description,
+          active: featureData.active
+        };
+        
+        fs.writeJsonSync(featuresFile, featuresData, { spaces: 2 });
+        
+        return res.json({
+          code: 0,
+          message: '功能模块更新成功',
+          data: featuresData.features[index]
+        });
+      } else {
+        // 创建新功能
+        const newFeature = {
+          id: Date.now().toString(),
+          name: featureData.name,
+          description: featureData.description || '',
+          active: featureData.active !== false,
+          createdAt: new Date().toISOString().split('T')[0]
+        };
+        
+        // 确保features数组存在
+        if (!Array.isArray(featuresData.features)) {
+          featuresData.features = [];
+        }
+        
+        featuresData.features.push(newFeature);
+        fs.writeJsonSync(featuresFile, featuresData, { spaces: 2 });
+        
+        return res.json({
+          code: 0,
+          message: '功能模块创建成功',
+          data: newFeature
+        });
+      }
+    }
+    
+    // 处理DELETE请求 - 删除功能模块
+    if (req.method === 'DELETE') {
+      const { id } = req.query;
+      
+      if (!id) {
+        return res.status(400).json({
+          code: 400,
+          message: '功能ID不能为空',
+          data: null
+        });
+      }
+      
+      let featuresData;
+      try {
+        featuresData = fs.readJsonSync(featuresFile);
+        if (!featuresData.features) {
+          featuresData = { features: [] };
+        }
+      } catch (err) {
+        // 读取出错时初始化
+        console.error('读取功能列表错误:', err);
+        featuresData = { features: [] };
+      }
+      
+      const index = featuresData.features.findIndex(item => item.id === id);
+      
+      if (index === -1) {
+        return res.status(404).json({
+          code: 404,
+          message: '功能模块不存在',
+          data: null
+        });
+      }
+      
+      // 删除功能
+      const deletedFeature = featuresData.features.splice(index, 1)[0];
+      fs.writeJsonSync(featuresFile, featuresData, { spaces: 2 });
+      
+      // 同时删除该功能的所有接口
+      if (fs.existsSync(interfacesFile)) {
+        try {
+          const interfacesData = fs.readJsonSync(interfacesFile);
+          if (interfacesData && Array.isArray(interfacesData.interfaces)) {
+            interfacesData.interfaces = interfacesData.interfaces.filter(item => item.featureId !== id);
+            fs.writeJsonSync(interfacesFile, interfacesData, { spaces: 2 });
+          }
+        } catch (err) {
+          console.error('处理接口文件错误:', err);
+        }
+      }
+      
+      return res.json({
+        code: 0,
+        message: '功能模块删除成功',
+        data: deletedFeature
+      });
+    }
+    
+    // 处理PATCH请求 - 部分更新功能模块
+    if (req.method === 'PATCH') {
+      const { id } = req.query;
+      const updateData = req.body;
+      
+      if (!id) {
+        return res.status(400).json({
+          code: 400,
+          message: '功能ID不能为空',
+          data: null
+        });
+      }
+      
+      let featuresData;
+      try {
+        featuresData = fs.readJsonSync(featuresFile);
+        if (!featuresData.features) {
+          featuresData = { features: [] };
+        }
+      } catch (err) {
+        console.error('读取功能列表错误:', err);
+        return res.status(500).json({
+          code: 500,
+          message: '读取功能列表失败',
+          data: null
+        });
+      }
+      
+      const index = featuresData.features.findIndex(item => item.id === id);
+      
+      if (index === -1) {
+        return res.status(404).json({
+          code: 404,
+          message: '功能模块不存在',
+          data: null
+        });
+      }
+      
+      // 更新部分字段
+      const updatedFeature = {
+        ...featuresData.features[index]
+      };
+      
+      // 只更新提供的字段
+      if (updateData.name !== undefined) {
+        updatedFeature.name = updateData.name;
+      }
+      
+      if (updateData.description !== undefined) {
+        updatedFeature.description = updateData.description;
+      }
+      
+      if (updateData.active !== undefined) {
+        updatedFeature.active = updateData.active;
+      }
+      
+      updatedFeature.updatedAt = new Date().toISOString();
+      
+      featuresData.features[index] = updatedFeature;
+      fs.writeJsonSync(featuresFile, featuresData, { spaces: 2 });
+      
+      return res.json({
+        code: 0,
+        message: '功能模块更新成功',
+        data: updatedFeature
+      });
+    }
+    
+    // 其他请求方法
+    return res.status(405).json({
+      code: 405,
+      message: '不支持的请求方法',
+      data: null
+    });
+  } catch (err) {
+    console.error('处理功能模块请求出错:', err);
+    return res.status(500).json({
+      code: 500,
+      message: '服务器内部错误: ' + err.message,
+      data: null
+    });
+  }
+}; 

package/app/cgi-bin/index.js

@@ -0,0 +1,31 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+module.exports = function(req, res) {
+  const dataDir = this.dataDir;
+  const featuresFile = path.join(dataDir, 'features.json');
+  const interfacesFile = path.join(dataDir, 'interfaces.json');
+  
+  // 确保配置文件存在
+  if (!fs.existsSync(featuresFile)) {
+    fs.writeJsonSync(featuresFile, { features: [] }, { spaces: 2 });
+  }
+  if (!fs.existsSync(interfacesFile)) {
+    fs.writeJsonSync(interfacesFile, { interfaces: [] }, { spaces: 2 });
+  }
+  
+  res.json({
+    code: 0,
+    message: '成功',
+    data: {
+      version: '0.2.0',
+      name: 'whistle.mock-plugin',
+      features: [
+        '支持Mock.js语法',
+        '支持自定义响应头',
+        '支持延迟响应',
+        '支持条件匹配'
+      ]
+    }
+  });
+};