json-api-mocker 3.0.0 → 3.1.0

package/README.md

@@ -1,6 +1,6 @@
 # JSON API Mocker
 
-A lightweight and flexible mock server with JSON configuration and visual management interface.
+A lightweight and flexible mock server that uses JSON configuration to quickly create RESTful APIs.
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/json-api-mocker" alt="npm version" />
@@ -10,57 +10,35 @@ A lightweight and flexible mock server with JSON configuration and visual manage
 
 ## ✨ Features
 
-- 🚀 Brand new visual management interface
-- 🚀 Support both configuration file and UI management
-- 🔄 Support all common HTTP methods
+- 🚀 Quick setup with JSON configuration
+- 🔄 Support for GET, POST, PUT, DELETE methods
+- 🖥️ Visual admin console, no JSON editing required
 - 📝 Automatic data persistence
 - 🔍 Built-in pagination support
-- 🛠 Customizable response structure
-- 🎭 Powerful data mocking with Mock.js
-- 📊 Real-time request logs and statistics
+- 🛠 Customizable response schemas
+- 🎭 Integration with Mock.js for powerful data mocking
+- 📤 File upload support
+- 🔌 Real-time communication with WebSocket
 - 💡 TypeScript support
 
 ## 📦 Installation
 
 ```bash
-npm install -g json-api-mocker
-```
-
-## 🚀 Quick Start
-
-The server uses fixed ports:
-- API Server: 35728
-- Web UI: 35729
-- WebSocket: 35730
+# Using npm
+npm install json-api-mocker
 
-### Method 1: Using Visual Interface (Recommended)
+# Using yarn
+yarn add json-api-mocker
 
-1. Create a `data.json` file:
-```json
-{
-  "server": {
-    "port": 35728,
-    "baseProxy": "/api"
-  },
-  "routes": []
-}
-```
-
-2. Start the server:
-```bash
-# Start server and open browser
-json-api-mocker -o
+# Using pnpm
+pnpm add json-api-mocker
 ```
 
-After starting, the browser will automatically open the management interface, where you can:
-1. Visually create and manage APIs
-2. View real-time request logs
-3. Monitor API call statistics
-4. Debug mock data online
+## 🚀 Quick Start
 
-### Method 2: Using Configuration File (Compatible with old version)
+### 1. Create Configuration File
 
-Create a `data.json` file:
+Create a `data.json` file in your project root:
 
 ```json
 {
@@ -70,21 +48,40 @@ Create a `data.json` file:
   },
   "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": "John",
+              "age": 30,
+              "city": "New York"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "path": "/upload/avatar",
+      "methods": {
+        "post": {
+          "type": "object",
+          "mock": {
+            "enabled": true,
+            "template": {
+              "success": true,
+              "message": "Upload successful",
               "data": {
-                "list|10": [{
-                  "id": "@id",
-                  "name": "@name",
-                  "email": "@email"
-                }]
+                "url": "@image('200x200')",
+                "filename": "@string(10).jpg",
+                "size": "@integer(1000, 1000000)"
               }
             }
           }
@@ -95,45 +92,129 @@ Create a `data.json` file:
 }
 ```
 
-Then start the server:
+### 2. Start the Server
+
+There are several ways to start the mock server:
 
 ```bash
+# Method 1: Using npx (Recommended)
+npx json-api-mocker
+
+# Method 2: Using npx with a custom config file
+npx json-api-mocker ./custom-config.json
+
+# Method 3: If installed globally
 json-api-mocker
+
+# Method 4: If installed as a project dependency
+# Add this to your package.json scripts:
+{
+  "scripts": {
+    "mock": "json-api-mocker"
+  }
+}
+# Then run:
+npm run mock
+```
+
+Now your mock server is running at `http://localhost:8080`!
+
+You'll see output like this:
+```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
 ```
 
-## 📖 Configuration
+## 🖥️ Visual Admin Console
+
+Don't want to write JSON config by hand? After starting the server, open the admin console in your browser:
+
+```
+http://localhost:8080/admin
+```
+
+The admin console provides the following features:
+
+- 📝 **Visual Editor**: Configure routes, methods, and Mock fields via forms — no JSON knowledge required
+- 🎨 **Field Builder**: Select field types (random name, age range, email, city, etc.) from a dropdown to auto-generate Mock.js templates
+- 💻 **JSON Source Editor**: Switch to source mode to edit JSON directly, with formatting and syntax checking
+- 👀 **API Preview**: View all available APIs; GET endpoints can be tested with one click
+- 💾 **One-click Save**: Save changes and they're automatically written back to `data.json`
+
+> 💡 After saving, static data changes take effect immediately; newly added routes require a server restart.
+
+## 📖 Configuration Guide
+
+For detailed configuration options, please refer to [CONFIG.md](./CONFIG.md).
 
 ### Server Configuration
 
+The `server` section configures basic server settings:
+
 ```json
 {
   "server": {
-    "port": 8080,      // Server port
-    "baseProxy": "/api" // API base path
+    "port": 8080,      // Server port number
+    "baseProxy": "/api" // Base path for all routes
   }
 }
 ```
 
-### API Configuration
+### Route Configuration
 
-Each API configuration includes:
+Each route can support multiple HTTP methods:
 
 ```json
 {
-  "id": "unique-id",    // API unique identifier
-  "route": {
-    "path": "/users",   // API path (without base path)
-    "methods": {        // Supported HTTP methods
-      "get": {
-        "status": 200,  // Response status code
-        "headers": {    // Custom response headers
-          "Content-Type": "application/json"
-        },
-        "response": {   // Response data (supports Mock.js syntax)
-          "code": 200,
+  "path": "/users",    // Route path
+  "methods": {
+    "get": {
+      "type": "array", // Response type: "array" or "object"
+      "pagination": {  // Optional pagination settings
+        "enabled": true,
+        "pageSize": 10,
+        "totalCount": 100
+      },
+      "response": []   // Response data
+    },
+    "post": {
+      "requestSchema": {  // Request body validation schema
+        "name": "string",
+        "age": "number"
+      },
+      "response": {
+        "success": true
+      }
+    }
+  }
+}
+```
+
+### File Upload Support
+
+You can configure file upload endpoints in your `data.json`:
+
+```json
+{
+  "path": "/upload/avatar",
+  "methods": {
+    "post": {
+      "type": "object",
+      "mock": {
+        "enabled": true,
+        "template": {
+          "success": true,
+          "message": "Upload successful",
           "data": {
-            "name": "@name",
-            "age": "@integer(18, 60)"
+            "url": "@image('200x200')",
+            "filename": "@string(10).jpg",
+            "size": "@integer(1000, 1000000)"
           }
         }
       }
@@ -142,44 +223,196 @@ Each API configuration includes:
 }
 ```
 
-## 🎮 Visual Interface Features
+#### Example Usage:
+
+```bash
+# Upload single file
+curl -X POST http://localhost:8080/api/upload/avatar \
+  -H "Content-Type: multipart/form-data" \
+  -F "avatar=@/path/to/your/image.jpg"
+
+# Upload multiple files
+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"
+```
+
+For detailed configuration options, please refer to [CONFIG.md](./CONFIG.md#file-upload-configuration).
+
+## 🎯 API Examples
 
-### 1. API Management
-- Create, edit, and delete APIs
-- Support multiple HTTP methods
-- Visual response data editor
-- Mock.js syntax hints
+### Basic CRUD Operations
 
-### 2. Real-time Logs
-- Request path and method
-- Response status and duration
-- Request parameters recording
-- Response data viewing
+#### Get Users List
+```bash
+curl http://localhost:8080/api/users
+```
+
+#### Get Single User
+```bash
+curl http://localhost:8080/api/users/1
+```
+
+#### Create User
+```bash
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Alice","age":25,"city":"Boston"}'
+```
+
+#### Update User
+```bash
+curl -X PUT http://localhost:8080/api/users/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Alice","age":26,"city":"Boston"}'
+```
 
-### 3. Statistics Dashboard
-- Total API count
-- Request volume monitoring
-- Average response time
-- Success rate statistics
+#### Delete User
+```bash
+curl -X DELETE http://localhost:8080/api/users/1
+```
 
-## 🔧 Command Line Options
+### Advanced Usage
 
+#### Pagination
 ```bash
-json-api-mocker [options]
+# Get page 2 with 10 items per page
+curl http://localhost:8080/api/users?page=2&pageSize=10
+```
+
+#### Custom Response Headers
+The server automatically adds these headers:
+- `X-Total-Count`: Total number of items (for paginated responses)
+
+## 🔧 Advanced Configuration
+
+### Dynamic Routes
+
+You can use URL parameters in routes:
+
+```json
+{
+  "path": "/users/:id/posts",
+  "methods": {
+    "get": {
+      "type": "array",
+      "response": []
+    }
+  }
+}
+```
+
+### Request Validation
+
+Add schema validation for POST/PUT requests:
+
+```json
+{
+  "requestSchema": {
+    "name": "string",
+    "age": "number",
+    "email": "string"
+  }
+}
+```
+
+### WebSocket Support
+
+You can configure WebSocket endpoints in your `data.json`:
+
+```json
+{
+  "websocket": {
+    "enabled": true,
+    "path": "/ws",
+    "events": {
+      "realtime-data": {
+        "mock": {
+          "enabled": true,
+          "interval": 5000,  // Send data every 5 seconds
+          "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"
+          }
+        }
+      }
+    }
+  }
+}
+```
 
-Options:
-  -p, --port <number>     Specify server port (default: 8080)
-  -c, --config <path>     Specify config file path (default: data.json)
-  -o, --open             Auto open management interface
-  -h, --help            Show help information
-  -v, --version         Show version number
+#### Client Usage Example:
+
+```javascript
+// Connect to WebSocket server
+const ws = new WebSocket('ws://localhost:8080/ws');
+
+// Handle connection open
+ws.onopen = () => {
+  console.log('Connected to WebSocket server');
+  
+  // Request real-time data
+  ws.send(JSON.stringify({
+    event: 'realtime-data'
+  }));
+};
+
+// Handle incoming messages
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+  // {
+  //   event: 'realtime-data',
+  //   data: {
+  //     timestamp: '2024-01-01 12:00:00',
+  //     value: 75,
+  //     status: 'normal'
+  //   }
+  // }
+};
+
+// Handle errors
+ws.onerror = (error) => {
+  console.error('WebSocket error:', error);
+};
+
+// Handle connection close
+ws.onclose = () => {
+  console.log('Disconnected from WebSocket server');
+};
 ```
 
+#### Features:
+- Event-based communication
+- Automatic data sending at specified intervals
+- Mock.js template support for dynamic data
+- Multiple event handlers
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
 ## 📄 License
 
 MIT © [Xiong Haiyin]
 
 ## 🙏 Acknowledgments
 
-- Thanks to all contributors and users
-- Special thanks to Mock.js for data mocking support
+- Express.js for the excellent web framework
+- All our contributors and users

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-export {};
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,41 +1,6 @@
-#!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const commander_1 = require("commander");
-const index_1 = require("./index");
-const path_1 = require("path");
-const express_1 = __importDefault(require("express"));
-const http_1 = require("http");
-const open_1 = __importDefault(require("open"));
-const WEB_PORT = 35729; // 前端页面端口
-const WS_PORT = 35730; // WebSocket 端口
-commander_1.program
-    .version(require('../package.json').version)
-    .option('-c, --config <path>', '配置文件路径', 'data.json')
-    .option('-o, --open', '自动打开浏览器', false)
-    .parse(process.argv);
-const options = commander_1.program.opts();
-// 启动 API Mock 服务器，不再传入端口参数，使用配置文件中的端口
-(0, index_1.startServer)({
-    config: options.config,
-    wsPort: WS_PORT
-});
-// 创建静态文件服务器来托管前端页面
-const app = (0, express_1.default)();
-const httpServer = (0, http_1.createServer)(app);
-// 使用打包后的前端文件
-app.use(express_1.default.static((0, path_1.join)(__dirname, '../web')));
-// 所有路由都返回 index.html
-app.get('*', (req, res) => {
-    res.sendFile((0, path_1.join)(__dirname, '../web/index.html'));
-});
-// 启动前端服务器（使用固定端口）
-httpServer.listen(WEB_PORT, () => {
-    console.log(`Web UI is running on http://localhost:${WEB_PORT}`);
-    if (options.open) {
-        (0, open_1.default)(`http://localhost:${WEB_PORT}`);
-    }
-});
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const configPath = process.argv[2] || 'data.json';
+(0, index_1.startServer)(configPath);

package/dist/index.d.ts

@@ -1,7 +1,3 @@
-interface StartOptions {
-    config?: string;
-    wsPort?: number;
-}
-export declare function startServer(options?: StartOptions): void;
-export { MockServer } from './server';
-export * from './types';
+export declare function startServer(configPath?: string): void;
+export { MockServer } from './server';
+export * from './types';

package/dist/index.js

@@ -1,48 +1,43 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockServer = exports.startServer = void 0;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const server_1 = require("./server");
-function startServer(options = {}) {
-    const configPath = options.config || 'data.json';
-    const fullPath = path_1.default.resolve(process.cwd(), configPath);
-    try {
-        const configContent = fs_1.default.readFileSync(fullPath, 'utf-8');
-        const config = JSON.parse(configContent);
-        const serverConfig = {
-            ...config.server,
-            wsPort: options.wsPort
-        };
-        const server = new server_1.MockServer(serverConfig, configPath);
-        server.start();
-    }
-    catch (error) {
-        console.error('Failed to start server:', error);
-        process.exit(1);
-    }
-}
-exports.startServer = startServer;
-if (require.main === module) {
-    startServer();
-}
-var server_2 = require("./server");
-Object.defineProperty(exports, "MockServer", { enumerable: true, get: function () { return server_2.MockServer; } });
-__exportStar(require("./types"), exports);
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockServer = exports.startServer = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const server_1 = require("./server");
+function startServer(configPath = 'data.json') {
+    const fullPath = path_1.default.resolve(process.cwd(), configPath);
+    try {
+        const configContent = fs_1.default.readFileSync(fullPath, 'utf-8');
+        const config = JSON.parse(configContent);
+        const server = new server_1.MockServer(config, configPath);
+        server.start();
+    }
+    catch (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+}
+exports.startServer = startServer;
+if (require.main === module) {
+    startServer();
+}
+var server_2 = require("./server");
+Object.defineProperty(exports, "MockServer", { enumerable: true, get: function () { return server_2.MockServer; } });
+__exportStar(require("./types"), exports);