json-api-mocker 3.0.0 → 3.1.0

package/CONFIG.md

@@ -302,3 +302,41 @@ You can configure file upload endpoints in your `data.json`:
     }
   }
 ```
+
+### WebSocket Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| enabled | boolean | Yes | Enable/disable WebSocket support |
+| path | string | Yes | WebSocket endpoint path |
+| events | object | No | Event configurations |
+
+#### Event Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| mock.enabled | boolean | Yes | Enable/disable mock data for this event |
+| mock.interval | number | No | Interval (ms) for automatic data sending |
+| mock.template | object | Yes | Mock.js template for response data |
+
+Example:
+```json
+{
+  "websocket": {
+    "enabled": true,
+    "path": "/ws",
+    "events": {
+      "event-name": {
+        "mock": {
+          "enabled": true,
+          "interval": 5000,
+          "template": {
+            "field1": "@value",
+            "field2|1-100": 1
+          }
+        }
+      }
+    }
+  }
+}
+```

package/README.ch.md

@@ -1,6 +1,6 @@
 # JSON API Mocker
 
-一个轻量级且灵活的 Mock 服务器，支持 JSON 配置和可视化界面管理。
+一个轻量级且灵活的 Mock 服务器，通过 JSON 配置快速创建 RESTful API。
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/json-api-mocker" alt="npm 版本" />
@@ -10,57 +10,35 @@
 
 ## ✨ 特性
 
-- 🚀 全新的可视化管理界面
-- 🚀 支持配置文件和 UI 两种使用方式
-- 🔄 支持所有常用 HTTP 方法
+- 🚀 通过 JSON 配置快速搭建
+- 🔄 支持 GET、POST、PUT、DELETE 方法
+- 🖥️ 可视化管理后台，无需手写 JSON
 - 📝 自动数据持久化
 - 🔍 内置分页支持
 - 🛠 可自定义响应结构
 - 🎭 集成 Mock.js 实现强大的数据模拟
-- 📊 实时请求日志和统计
+- 📤 支持文件上传
+- 🔌 支持 WebSocket 实时通信
 - 💡 TypeScript 支持
 
 ## 📦 安装
 
 ```bash
-npm install -g json-api-mocker
-```
-
-## 🚀 快速开始
-
-服务器使用固定端口：
-- API 服务器：35728
-- Web 界面：35729
-- WebSocket：35730
+# 使用 npm
+npm install json-api-mocker
 
-### 方式一：使用可视化界面（推荐）
+# 使用 yarn
+yarn add json-api-mocker
 
-1. 创建 `data.json` 文件：
-```json
-{
-  "server": {
-    "port": 35728,
-    "baseProxy": "/api"
-  },
-  "routes": []
-}
-```
-
-2. 启动服务器：
-```bash
-# 启动服务器并打开浏览器
-json-api-mocker -o
+# 使用 pnpm
+pnpm add json-api-mocker
 ```
 
-启动后，浏览器会自动打开管理界面，你可以：
-1. 可视化创建和管理 API
-2. 实时查看请求日志
-3. 监控 API 调用统计
-4. 在线调试 Mock 数据
+## 🚀 快速开始
 
-### 方式二：使用配置文件（兼容旧版本）
+### 1. 创建配置文件
 
-创建 `data.json` 文件：
+在项目根目录创建 `data.json` 文件：
 
 ```json
 {
@@ -70,21 +48,40 @@ json-api-mocker -o
   },
   "routes": [
     {
-      "id": "user-api",
-      "route": {
-        "path": "/users",
-        "methods": {
-          "get": {
-            "status": 200,
-            "response": {
-              "code": 200,
-              "message": "success",
+      "path": "/users",
+      "methods": {
+        "get": {
+          "type": "array",
+          "pagination": {
+            "enabled": true,
+            "pageSize": 10,
+            "totalCount": 100
+          },
+          "response": [
+            {
+              "id": 1,
+              "name": "张三",
+              "age": 30,
+              "city": "北京"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "path": "/upload/avatar",
+      "methods": {
+        "post": {
+          "type": "object",
+          "mock": {
+            "enabled": true,
+            "template": {
+              "success": true,
+              "message": "上传成功",
               "data": {
-                "list|10": [{
-                  "id": "@id",
-                  "name": "@cname",
-                  "email": "@email"
-                }]
+                "url": "@image('200x200')",
+                "filename": "@string(10).jpg",
+                "size": "@integer(1000, 1000000)"
               }
             }
           }
@@ -95,45 +92,129 @@ json-api-mocker -o
 }
 ```
 
-然后启动服务器：
+### 2. 启动服务器
+
+有多种方式可以启动 Mock 服务器：
 
 ```bash
+# 方式一：使用 npx（推荐）
+npx json-api-mocker
+
+# 方式二：使用 npx 并指定配置文件
+npx json-api-mocker ./custom-config.json
+
+# 方式三：如果全局安装了包
 json-api-mocker
+
+# 方式四：如果作为项目依赖安装
+# 在 package.json 的 scripts 中添加：
+{
+  "scripts": {
+    "mock": "json-api-mocker"
+  }
+}
+# 然后运行：
+npm run mock
+```
+
+现在你的 Mock 服务器已经在 `http://localhost:8080` 运行了！
+
+你会看到类似这样的输出：
+```bash
+Mock 服务器已启动：
+- HTTP 地址：http://localhost:8080
+- 管理后台：http://localhost:8080/admin
+- 基础路径：/api
+可用的接口：
+  GET http://localhost:8080/api/users
+  POST http://localhost:8080/api/users
+  POST http://localhost:8080/api/upload/avatar
 ```
 
-## 📖 配置说明
+## 🖥️ 可视化管理后台
+
+不想手写 JSON 配置文件？启动服务后，打开浏览器访问管理后台：
+
+```
+http://localhost:8080/admin
+```
+
+管理后台提供以下功能：
+
+- 📝 **可视化编辑**：通过表单配置路由、接口方法、Mock 字段，无需了解 JSON 格式
+- 🎨 **字段构建器**：通过下拉菜单选择字段类型（随机姓名、年龄范围、邮箱、城市等），自动生成 Mock.js 模板
+- 💻 **JSON 源码编辑**：切换到源码模式直接编辑 JSON，支持格式化和语法检查
+- 👀 **接口预览**：查看所有可用接口，GET 接口可直接点击测试
+- 💾 **一键保存**：修改后点击保存，配置自动写回 `data.json` 文件
+
+> 💡 保存配置后，静态数据修改会立即生效；新增路由需要重启服务才能完全生效。
+
+## 📖 配置指南
+
+详细配置请参考 [CONFIG.ch.md](./CONFIG.ch.md)。
 
 ### 服务器配置
 
+`server` 部分配置基本的服务器设置：
+
 ```json
 {
   "server": {
     "port": 8080,      // 服务器端口号
-    "baseProxy": "/api" // API 基础路径
+    "baseProxy": "/api" // 所有路由的基础路径
   }
 }
 ```
 
-### API 配置
+### 路由配置
 
-每个 API 配置包含：
+每个路由可以支持多个 HTTP 方法：
 
 ```json
 {
-  "id": "unique-id",    // API 唯一标识
-  "route": {
-    "path": "/users",   // API 路径（不含基础路径）
-    "methods": {        // 支持的 HTTP 方法
-      "get": {
-        "status": 200,  // 响应状态码
-        "headers": {    // 自定义响应头
-          "Content-Type": "application/json"
-        },
-        "response": {   // 响应数据（支持 Mock.js 语法）
-          "code": 200,
+  "path": "/users",    // 路由路径
+  "methods": {
+    "get": {
+      "type": "array", // 响应类型：array 或 object
+      "pagination": {  // 可选的分页设置
+        "enabled": true,
+        "pageSize": 10,
+        "totalCount": 100
+      },
+      "response": []   // 响应数据
+    },
+    "post": {
+      "requestSchema": {  // 请求体验证模式
+        "name": "string",
+        "age": "number"
+      },
+      "response": {
+        "success": true
+      }
+    }
+  }
+}
+```
+
+### 文件上传支持
+
+你可以在 `data.json` 中配置文件上传接口：
+
+```json
+{
+  "path": "/upload/avatar",
+  "methods": {
+    "post": {
+      "type": "object",
+      "mock": {
+        "enabled": true,
+        "template": {
+          "success": true,
+          "message": "上传成功",
           "data": {
-            "name": "@name",
-            "age": "@integer(18, 60)"
+            "url": "@image('200x200')",
+            "filename": "@string(10).jpg",
+            "size": "@integer(1000, 1000000)"
           }
         }
       }
@@ -142,44 +223,196 @@ json-api-mocker
 }
 ```
 
-## 🎮 可视化界面功能
+#### 使用示例：
+
+```bash
+# 上传单个文件
+curl -X POST http://localhost:8080/api/upload/avatar \
+  -H "Content-Type: multipart/form-data" \
+  -F "avatar=@/path/to/your/image.jpg"
+
+# 上传多个文件
+curl -X POST http://localhost:8080/api/upload/images \
+  -H "Content-Type: multipart/form-data" \
+  -F "images=@/path/to/image1.jpg" \
+  -F "images=@/path/to/image2.jpg"
+```
+
+详细配置选项请参考 [CONFIG.ch.md](./CONFIG.ch.md#文件上传配置)。
+
+## 🎯 API 示例
 
-### 1. API 管理
-- 创建、编辑、删除 API
-- 支持多种 HTTP 方法
-- 可视化编辑响应数据
-- Mock.js 语法提示
+### 基本的 CRUD 操作
 
-### 2. 实时日志
-- 请求路径和方法
-- 响应状态和耗时
-- 请求参数记录
-- 响应数据查看
+#### 获取用户列表
+```bash
+curl http://localhost:8080/api/users
+```
+
+#### 获取单个用户
+```bash
+curl http://localhost:8080/api/users/1
+```
+
+#### 创建用户
+```bash
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"李四","age":25,"city":"上海"}'
+```
+
+#### 更新用户
+```bash
+curl -X PUT http://localhost:8080/api/users/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name":"李四","age":26,"city":"上海"}'
+```
 
-### 3. 统计面板
-- API 总数统计
-- 请求量监控
-- 平均响应时间
-- 成功率统计
+#### 删除用户
+```bash
+curl -X DELETE http://localhost:8080/api/users/1
+```
 
-## 🔧 命令行参数
+### 高级用法
 
+#### 分页
 ```bash
-json-api-mocker [options]
+# 获取第2页，每页10条数据
+curl http://localhost:8080/api/users?page=2&pageSize=10
+```
+
+#### 自定义响应头
+服务器自动添加以下响应头：
+- `X-Total-Count`：数据总条数（用于分页响应）
+
+## 🔧 高级配置
+
+### 动态路由
+
+你可以在路由中使用 URL 参数：
+
+```json
+{
+  "path": "/users/:id/posts",
+  "methods": {
+    "get": {
+      "type": "array",
+      "response": []
+    }
+  }
+}
+```
+
+### 请求验证
+
+为 POST/PUT 请求添加模式验证：
+
+```json
+{
+  "requestSchema": {
+    "name": "string",
+    "age": "number",
+    "email": "string"
+  }
+}
+```
+
+### WebSocket 支持
+
+你可以在 `data.json` 中配置 WebSocket 接口：
+
+```json
+{
+  "websocket": {
+    "enabled": true,
+    "path": "/ws",
+    "events": {
+      "realtime-data": {
+        "mock": {
+          "enabled": true,
+          "interval": 5000,  // 每5秒发送一次数据
+          "template": {
+            "timestamp": "@datetime",
+            "value|1-100": 1,
+            "status|1": ["normal", "warning", "error"]
+          }
+        }
+      },
+      "user-status": {
+        "mock": {
+          "enabled": true,
+          "template": {
+            "userId|+1": 1,
+            "status|1": ["online", "offline", "away"],
+            "lastActive": "@datetime"
+          }
+        }
+      }
+    }
+  }
+}
+```
 
-选项：
-  -p, --port <number>     指定服务器端口号（默认：8080）
-  -c, --config <path>     指定配置文件路径（默认：data.json）
-  -o, --open             自动打开管理界面
-  -h, --help            显示帮助信息
-  -v, --version         显示版本号
+#### 客户端使用示例：
+
+```javascript
+// 连接 WebSocket 服务器
+const ws = new WebSocket('ws://localhost:8080/ws');
+
+// 处理连接打开
+ws.onopen = () => {
+  console.log('已连接到 WebSocket 服务器');
+  
+  // 请求实时数据
+  ws.send(JSON.stringify({
+    event: 'realtime-data'
+  }));
+};
+
+// 处理接收到的消息
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('收到数据:', data);
+  // {
+  //   event: 'realtime-data',
+  //   data: {
+  //     timestamp: '2024-01-01 12:00:00',
+  //     value: 75,
+  //     status: 'normal'
+  //   }
+  // }
+};
+
+// 处理错误
+ws.onerror = (error) => {
+  console.error('WebSocket 错误:', error);
+};
+
+// 处理连接关闭
+ws.onclose = () => {
+  console.log('与 WebSocket 服务器断开连接');
+};
 ```
 
+#### 特性：
+- 基于事件的通信
+- 支持指定间隔自动发送数据
+- 支持 Mock.js 模板生成动态数据
+- 支持多个事件处理器
+
+## 🤝 贡献指南
+
+1. Fork 本仓库
+2. 创建你的特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交你的改动 (`git commit -m '添加一些很棒的特性'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 开启一个 Pull Request
+
 ## 📄 许可证
 
 MIT © [熊海银]
 
 ## 🙏 致谢
 
-- 感谢所有贡献者和用户
-- 特别感谢 Mock.js 提供数据模拟支持
+- 感谢 Express.js 提供出色的 Web 框架
+- 感谢所有贡献者和用户