json-api-mocker 2.3.0 → 3.0.0

package/DESIGN.md

@@ -0,0 +1,227 @@
+# JSON API Mocker 设计思路文档
+
+## 1. 项目架构设计
+
+### 1.1 核心模块划分
+```
+src/
+├── types.ts      # 类型定义
+├── server.ts     # 服务器核心逻辑
+├── index.ts      # 入口文件
+└── cli.ts        # 命令行工具
+```
+
+### 1.2 设计原则
+- **配置驱动**: 通过 JSON 配置文件定义 API，而不是代码
+- **约定优于配置**: 提供合理的默认值，减少配置复杂度
+- **单一职责**: 每个模块只负责一个功能
+- **开闭原则**: 扩展开放，修改关闭
+
+## 2. 关键技术决策
+
+### 2.1 为什么选择 JSON 配置文件
+- **优点**:
+  - 零代码门槛
+  - 配置直观易读
+  - 方便版本控制
+  - 易于修改和共享
+- **缺点**:
+  - 灵活性相对较低
+  - 不支持复杂逻辑
+
+### 2.2 为什么选择文件系统而不是数据库
+- **优点**:
+  - 无需额外依赖
+  - 配置即数据，直观明了
+  - 方便迁移和备份
+- **缺点**:
+  - 并发性能较差
+  - 不适合大规模数据
+
+### 2.3 为什么使用 TypeScript
+- 类型安全
+- 更好的开发体验
+- 自动生成类型声明文件
+- 便于维护和重构
+
+## 3. 核心功能实现
+
+### 3.1 路由系统设计
+```typescript
+interface RouteConfig {
+  path: string;
+  methods: {
+    [key: string]: MethodConfig;
+  };
+}
+
+// 支持 RESTful API 的标准方法
+type HttpMethod = 'get' | 'post' | 'put' | 'delete';
+```
+
+### 3.2 数据持久化方案
+```typescript
+class MockServer {
+  private saveConfig() {
+    // 同步写入确保数据一致性
+    fs.writeFileSync(this.configPath, JSON.stringify(this.config, null, 2));
+  }
+}
+```
+
+### 3.3 分页实现
+```typescript
+interface PaginationConfig {
+  enabled: boolean;
+  pageSize: number;
+  totalCount: number;
+}
+
+// 分页处理逻辑
+const handlePagination = (data: any[], page: number, pageSize: number) => {
+  const start = (page - 1) * pageSize;
+  return data.slice(start, start + pageSize);
+};
+```
+
+## 4. 问题解决方案
+
+### 4.1 并发写入问题
+- **问题**: 多个请求同时修改配置文件可能导致数据不一致
+- **解决方案**:
+  1. 使用同步写入
+  2. 考虑添加文件锁
+  3. 实现写入队列
+
+### 4.2 动态路由参数
+- **问题**: 如何支持 `/users/:id` 这样的动态路径
+- **解决方案**:
+  ```typescript
+  // 使用 Express 的路由参数功能
+  app.get(`${baseProxy}${path}/:id`, (req, res) => {
+    const id = req.params.id;
+    // 处理逻辑
+  });
+  ```
+
+### 4.3 类型安全
+- **问题**: 如何确保运行时类型安全
+- **解决方案**:
+  ```typescript
+  // 请求体验证
+  interface RequestSchema {
+    [key: string]: 'string' | 'number' | 'boolean';
+  }
+  
+  const validateRequest = (body: any, schema: RequestSchema) => {
+    // 实现验证逻辑
+  };
+  ```
+
+## 5. 性能优化
+
+### 5.1 当前实现
+- 同步文件操作
+- 内存中保存配置副本
+- 简单的错误处理
+
+### 5.2 可能的优化方向
+1. **缓存优化**
+   ```typescript
+   class Cache {
+     private static instance: Cache;
+     private store: Map<string, any>;
+     
+     public get(key: string) {
+       return this.store.get(key);
+     }
+   }
+   ```
+
+2. **并发处理**
+   ```typescript
+   class WriteQueue {
+     private queue: Array<() => Promise<void>>;
+     
+     public async add(task: () => Promise<void>) {
+       this.queue.push(task);
+       await this.process();
+     }
+   }
+   ```
+
+## 6. 扩展性设计
+
+### 6.1 中间件支持
+```typescript
+interface ServerConfig {
+  middleware?: {
+    before?: Function[];
+    after?: Function[];
+  };
+}
+```
+
+### 6.2 自定义响应处理
+```typescript
+interface MethodConfig {
+  transform?: (data: any) => any;
+  headers?: Record<string, string>;
+}
+```
+
+## 7. 未来规划
+
+### 7.1 短期目标
+- ✅ 添加请求日志 (Completed in v1.2.0)
+- ✅ 支持文件上传 (Completed in v1.2.5)
+- ✅ 添加测试用例 (Completed in v1.2.6)
+
+### 7.2 长期目标
+- ✅ 提供 Web 界面 (Completed in v2.0.0)
+- 支持 WebSocket
+- 支持数据库存储
+- 支持集群部署
+
+## 8. 最佳实践
+
+### 8.1 配置文件组织
+```json
+{
+  "server": {
+    "port": 8080,
+    "baseProxy": "/api"
+  },
+  "routes": [
+    {
+      "path": "/users",
+      "methods": {
+        "get": { ... },
+        "post": { ... }
+      }
+    }
+  ]
+}
+```
+
+### 8.2 错误处理
+```typescript
+class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+const errorHandler = (err: Error, req: Request, res: Response) => {
+  if (err instanceof ApiError) {
+    res.status(err.status).json({ error: err.message });
+  }
+};
+```
+
+## 9. 总结
+
+本项目的核心是通过配置驱动的方式简化 Mock 服务器的搭建过程。虽然在性能和功能上有一些限制，但对于前端开发中的 Mock 需求来说是一个很好的解决方案。通过合理的模块划分和接口设计，我们既保证了代码的可维护性，也为未来的功能扩展留下了空间。 

package/README.ch.md

@@ -1,6 +1,6 @@
 # JSON API Mocker
 
-一个轻量级且灵活的 Mock 服务器，通过 JSON 配置快速创建 RESTful API。
+一个轻量级且灵活的 Mock 服务器，支持 JSON 配置和可视化界面管理。
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/json-api-mocker" alt="npm 版本" />
@@ -10,33 +10,57 @@
 
 ## ✨ 特性
 
-- 🚀 通过 JSON 配置快速搭建
-- 🔄 支持 GET、POST、PUT、DELETE 方法
+- 🚀 全新的可视化管理界面
+- 🚀 支持配置文件和 UI 两种使用方式
+- 🔄 支持所有常用 HTTP 方法
 - 📝 自动数据持久化
 - 🔍 内置分页支持
 - 🛠 可自定义响应结构
 - 🎭 集成 Mock.js 实现强大的数据模拟
-- 📤 支持文件上传
+- 📊 实时请求日志和统计
 - 💡 TypeScript 支持
 
 ## 📦 安装
 
 ```bash
-# 使用 npm
-npm install json-api-mocker
+npm install -g json-api-mocker
+```
+
+## 🚀 快速开始
+
+服务器使用固定端口：
+- API 服务器：35728
+- Web 界面：35729
+- WebSocket：35730
+
+### 方式一：使用可视化界面（推荐）
 
-# 使用 yarn
-yarn add json-api-mocker
+1. 创建 `data.json` 文件：
+```json
+{
+  "server": {
+    "port": 35728,
+    "baseProxy": "/api"
+  },
+  "routes": []
+}
+```
 
-# 使用 pnpm
-pnpm add json-api-mocker
+2. 启动服务器：
+```bash
+# 启动服务器并打开浏览器
+json-api-mocker -o
 ```
 
-## 🚀 快速开始
+启动后，浏览器会自动打开管理界面，你可以：
+1. 可视化创建和管理 API
+2. 实时查看请求日志
+3. 监控 API 调用统计
+4. 在线调试 Mock 数据
 
-### 1. 创建配置文件
+### 方式二：使用配置文件（兼容旧版本）
 
-在项目根目录创建 `data.json` 文件：
+创建 `data.json` 文件：
 
 ```json
 {
@@ -46,40 +70,21 @@ pnpm add json-api-mocker
   },
   "routes": [
     {
-      "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": "上传成功",
+      "id": "user-api",
+      "route": {
+        "path": "/users",
+        "methods": {
+          "get": {
+            "status": 200,
+            "response": {
+              "code": 200,
+              "message": "success",
               "data": {
-                "url": "@image('200x200')",
-                "filename": "@string(10).jpg",
-                "size": "@integer(1000, 1000000)"
+                "list|10": [{
+                  "id": "@id",
+                  "name": "@cname",
+                  "email": "@email"
+                }]
               }
             }
           }
@@ -90,110 +95,45 @@ pnpm add json-api-mocker
 }
 ```
 
-### 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://localhost:8080
-- 基础路径：/api
-可用的接口：
-  GET http://localhost:8080/api/users
-  POST http://localhost:8080/api/users
-  POST http://localhost:8080/api/upload/avatar
-```
-
-## 📖 配置指南
-
-详细配置请参考 [CONFIG.ch.md](./CONFIG.ch.md)。
+## 📖 配置说明
 
 ### 服务器配置
 
-`server` 部分配置基本的服务器设置：
-
 ```json
 {
   "server": {
     "port": 8080,      // 服务器端口号
-    "baseProxy": "/api" // 所有路由的基础路径
+    "baseProxy": "/api" // API 基础路径
   }
 }
 ```
 
-### 路由配置
+### API 配置
 
-每个路由可以支持多个 HTTP 方法：
+每个 API 配置包含：
 
 ```json
 {
-  "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": "上传成功",
+  "id": "unique-id",    // API 唯一标识
+  "route": {
+    "path": "/users",   // API 路径（不含基础路径）
+    "methods": {        // 支持的 HTTP 方法
+      "get": {
+        "status": 200,  // 响应状态码
+        "headers": {    // 自定义响应头
+          "Content-Type": "application/json"
+        },
+        "response": {   // 响应数据（支持 Mock.js 语法）
+          "code": 200,
           "data": {
-            "url": "@image('200x200')",
-            "filename": "@string(10).jpg",
-            "size": "@integer(1000, 1000000)"
+            "name": "@name",
+            "age": "@integer(18, 60)"
           }
         }
       }
@@ -202,113 +142,44 @@ Mock 服务器已启动：
 }
 ```
 
-#### 使用示例：
-
-```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 操作
-
-#### 获取用户列表
-```bash
-curl http://localhost:8080/api/users
-```
-
-#### 获取单个用户
-```bash
-curl http://localhost:8080/api/users/1
-```
+### 2. 实时日志
+- 请求路径和方法
+- 响应状态和耗时
+- 请求参数记录
+- 响应数据查看
 
-#### 创建用户
-```bash
-curl -X POST http://localhost:8080/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"李四","age":25,"city":"上海"}'
-```
+### 3. 统计面板
+- API 总数统计
+- 请求量监控
+- 平均响应时间
+- 成功率统计
 
-#### 更新用户
-```bash
-curl -X PUT http://localhost:8080/api/users/1 \
-  -H "Content-Type: application/json" \
-  -d '{"name":"李四","age":26,"city":"上海"}'
-```
+## 🔧 命令行参数
 
-#### 删除用户
 ```bash
-curl -X DELETE http://localhost:8080/api/users/1
-```
-
-### 高级用法
+json-api-mocker [options]
 
-#### 分页
-```bash
-# 获取第2页，每页10条数据
-curl http://localhost:8080/api/users?page=2&pageSize=10
+选项：
+  -p, --port <number>     指定服务器端口号（默认：8080）
+  -c, --config <path>     指定配置文件路径（默认：data.json）
+  -o, --open             自动打开管理界面
+  -h, --help            显示帮助信息
+  -v, --version         显示版本号
 ```
 
-#### 自定义响应头
-服务器自动添加以下响应头：
-- `X-Total-Count`：数据总条数（用于分页响应）
-
-## 🔧 高级配置
-
-### 动态路由
-
-你可以在路由中使用 URL 参数：
-
-```json
-{
-  "path": "/users/:id/posts",
-  "methods": {
-    "get": {
-      "type": "array",
-      "response": []
-    }
-  }
-}
-```
-
-### 请求验证
-
-为 POST/PUT 请求添加模式验证：
-
-```json
-{
-  "requestSchema": {
-    "name": "string",
-    "age": "number",
-    "email": "string"
-  }
-}
-```
-
-## 🤝 贡献指南
-
-1. Fork 本仓库
-2. 创建你的特性分支 (`git checkout -b feature/amazing-feature`)
-3. 提交你的改动 (`git commit -m '添加一些很棒的特性'`)
-4. 推送到分支 (`git push origin feature/amazing-feature`)
-5. 开启一个 Pull Request
-
 ## 📄 许可证
 
 MIT © [熊海银]
 
 ## 🙏 致谢
 
-- 感谢 Express.js 提供出色的 Web 框架
-- 感谢所有贡献者和用户
+- 感谢所有贡献者和用户
+- 特别感谢 Mock.js 提供数据模拟支持