mm_os 3.3.1 → 4.0.0

package/README.md

@@ -1,105 +1,497 @@
-# 服务端框架
-
-#### 介绍
-这是一个**5星评级**服务端框架，用于快速构建网站、游戏、小程序、AIOT服务端。框架经过全面优化，达到了5星评级标准，在性能、稳定性、安全性、可维护性、功能完整性和二次开发上手难度方面均有出色表现。
-
-#### 软件架构
-由koa网站框架 + art-template模板引擎 + mm(热拔插)插件机制 + mysql数据库 + redis缓存 + jwt鉴权 + 等等组成。
-
-#### 5星评级达成情况
-
-✅ **性能**: 5/5 - 实现了高效缓存机制、性能监控和优化的路由系统
-✅ **稳定性**: 5/5 - 实现了熔断器模式、自动重试机制和完善的错误处理
-✅ **安全性**: 5/5 - 实现了HTTPS支持、CSRF保护、速率限制和敏感数据保护
-✅ **可维护性**: 5/5 - 实现了单元测试框架、统一日志系统和代码规范
-✅ **功能完整性**: 5/5 - 实现了全面的路由系统、配置管理和完整工具链
-✅ **二次开发上手难度**: 5/5 (极简) - 提供了详细的入门指南、API文档和丰富的示例代码
-
-#### 5星功能亮点
-
-### ✅ 性能优化
-- **缓存集成** - 高效数据缓存机制减少数据库压力
-- **性能监控** - 内置性能指标收集和分析
-- **优化的路由系统** - 支持RESTful API和参数验证
-
-### ✅ 稳定性增强
-- **熔断器模式** - 防止级联失败，提高系统稳定性
-- **自动重试机制** - 关键操作智能重试
-- **统一错误处理** - 完善的错误捕获和日志记录
-
-### ✅ 安全性提升
-- **HTTPS支持** - 完整的TLS/SSL配置
-- **CSRF保护** - 防止跨站请求伪造
-- **速率限制** - 防止暴力攻击和DoS攻击
-- **敏感数据保护** - 自动检测和过滤敏感信息
-
-### ✅ 可维护性保障
-- **单元测试框架** - 内置测试工具和断言库
-- **统一日志系统** - 结构化日志便于问题排查
-- **代码规范** - 遵循现代JavaScript最佳实践
-
-### ✅ 功能完整性
-- **路由系统** - 支持RESTful、中间件、路由组和参数验证
-- **配置管理** - 增强版配置管理支持多格式和环境变量
-- **工具集合** - 丰富的工具函数支持各类开发需求
-
-#### 安装教程
-新建一个目录，然后在当前打开命令提示符，输入以下命令进行初始化
-``` command
-npm init
+# MOS 服务端架构
+
+[![npm version](https://badge.fury.io/js/mm_os.svg)](https://badge.fury.io/js/mm_os)
+[![npm downloads](https://img.shields.io/npm/dm/mm_os.svg)](https://www.npmjs.com/package/mm_os)
+[![License](https://img.shields.io/npm/l/mm_os.svg)](https://gitee.com/qiuwenwu91/mm_os/blob/master/LICENSE)
+
+## 项目简介
+
+MOS 是一个轻量级的服务端架构，提供了完整的服务端开发框架，包括 Web、WebSocket、MQTT、Socket 等多种通信协议支持，以及丰富的组件和模块。
+
+适用于快速构建网站、小程序后台、AI应用、物联网应用、中小型游戏服务端。
+
+## 核心功能
+
+- **多协议支持**：Web、WebSocket、MQTT、Socket
+- **模块化设计**：应用、模组、中间件、通知器、消息发送器、广播器
+- **基础设施**：数据库、缓存、日志、文件管理
+- **事件驱动**：基于事件总线的异步处理
+- **插件系统**：支持功能扩展
+
+## 设计理念：配置与逻辑分离
+
+MOS 框架的核心设计原则是 **配置与逻辑分离**。无论是 `core` 核心模块还是 `com` 公共组件，每个功能模块都遵循统一的结构：
+
+### 模块组成
+
+每个模块由以下文件组成：
+
+| 文件类型 | 文件名 | 作用 |
+|----------|--------|------|
+| **配置文件** | `*.json` | 声明式定义模块的配置参数、元数据 |
+| **逻辑文件** | `index.js` | 实现模块的业务逻辑和功能 |
+
+### 设计优势
+
+**1. 声明式配置**
+- JSON 文件用于声明式定义模块的元数据和配置项
+- 无需编写代码即可完成模块注册和参数配置
+- 便于通过可视化工具进行管理和配置
+
+**2. 逻辑与配置解耦**
+- 配置变化无需修改代码，降低维护成本
+- 相同的业务逻辑可以通过不同配置复用
+- 配置文件可以独立版本管理和部署
+
+**3. 自动化能力**
+- 框架可自动扫描 JSON 配置完成模块注册
+- 自动生成文档和配置表单
+- 自动进行参数验证，减少重复代码
+
+**4. 热更新支持**
+- 配置文件可热更新，无需重启服务
+- 支持动态添加/修改模块配置
+
+**5. 团队协作优化**
+- 配置人员和开发人员可并行工作
+- 非开发人员也能参与模块配置
+- 统一的配置格式降低沟通成本
+
+### 模块类型
+
+**core 核心模块**：框架基础模块，包括应用(app)、控制器(controller)、模型(model)、逻辑(logic)、插件(plugin)、服务(service)、视图(view)、中间件(middleware)等。
+
+**com 公共组件**：可复用的公共组件，包括数据库(sql)、缓存(cache)、API管理(api)、事件(event)、任务(task)、静态资源(static)、模板(template)、MQTT、Socket等。
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install mm_os
 ```
-然后根据提示进行配置，配置完成后，输入以下指令进行安装
-``` command
-npm i mm_os
+
+### 基本用法
+
+```javascript
+const { MM_os } = require('mm_os');
+
+// 设置运行路径
+$.run_path = __dirname;
+
+// 创建服务器实例
+const server = new MM_os({
+  web: {
+    host: '0.0.0.0',
+    port: 8000,
+    socket: true
+  },
+  mysql: {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: '123456',
+    database: 'test'
+  },
+  cache: {
+    way: 'memory'
+  }
+});
+
+// 启动服务器
+async function startServer() {
+  await server.init();
+  await server.start();
+  console.log('服务器启动成功');
+}
+
+startServer();
 ```
 
-#### 使用说明
-安装完成后，目录下新建一个index.js文件，在命令行输入以下代码，然后运行即可
+## 项目目录结构
+
+基于 MOS 框架开发的项目采用标准化目录结构：
+
+```
+├── app/                    # 应用目录，包含多个独立应用
+│   ├── app_name/           # 应用名称
+│   │   ├── event_api/      # 事件API目录
+│   │   │   ├── web/        # Web路由处理
+│   │   │   │   ├── event.json    # 事件配置
+│   │   │   │   └── main.js       # 入口文件
+│   │   │   ├── api/        # API接口路由
+│   │   │   ├── client/     # 客户端接口路由
+│   │   │   └── manage/     # 管理后台路由
+│   │   ├── plugin/         # 插件目录
+│   │   │   ├── main/       # 主插件（业务逻辑）
+│   │   │   │   └── api_{app}_{channel}/{api_name}/
+│   │   │   │       ├── api.json   # API配置
+│   │   │   │       ├── param.json # 参数验证配置
+│   │   │   │       └── index.js   # API实现
+│   │   │   └── server/     # 服务端插件（数据管理）
+│   │   ├── pendant/        # 挂件组件目录
+│   │   ├── static/         # 静态资源目录
+│   │   ├── app.json        # 应用配置
+│   │   └── index.js        # 应用入口
+├── cache/                  # 缓存配置目录
+├── com/                    # 公共组件目录
+├── config/                 # 全局配置目录
+│   ├── local.json          # 本地配置
+│   ├── development.json    # 开发环境配置
+│   └── production.json     # 生产环境配置
+├── db/                     # 数据库文件目录（SQLite等）
+├── static/                 # 全局静态资源
+├── index.js                # 项目入口
+└── config.json             # 主配置文件
+```
+
+## 应用开发
+
+### 创建应用
+
+每个应用包含独立的业务逻辑，应用配置文件 `app.json`：
+
+```json
+{
+  "name": "user",
+  "version": "1.0",
+  "title": "用户",
+  "description": "用于用户身份验证",
+  "author": "developer",
+  "scope": "server",
+  "main": "./index.js",
+  "func_name": "main",
+  "sort": 10,
+  "state": 1,
+  "sql": {
+    "way": "mysql",
+    "mysql": {
+      "host": "127.0.0.1",
+      "port": 3306,
+      "user": "root",
+      "password": "password",
+      "database": "example"
+    }
+  },
+  "cache": {
+    "way": "redis"
+  }
+}
+```
+
+### 事件路由配置 (event.json)
+
+定义应用的路由规则：
+
+```json
+{
+  "/api/user/list": {
+    "method": "GET",
+    "title": "获取用户列表",
+    "auth": false
+  },
+  "/api/user/create": {
+    "method": "POST",
+    "title": "创建用户",
+    "auth": true
+  },
+  "/user/*": {
+    "method": "ALL",
+    "title": "用户页面路由",
+    "auth": false
+  }
+}
+```
+
+### 创建 API 接口
+
+API 是 MOS 框架的核心组件，每个 API 包含三个文件：
+
+#### 1. api.json - API 配置
+
+```json
+{
+  "name": "user_sign_in",
+  "title": "账户登录",
+  "description": "用户登录接口，支持账号密码、手机号验证码、社交账号登录",
+  "path": "/api/user/sign_in",
+  "type": "api",
+  "method": "ALL",
+  "cache": 0,
+  "param_path": "./param.json",
+  "check_param": true,
+  "sort": 1
+}
+```
+
+**api.json 字段说明：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | API 唯一标识 |
+| title | string | 是 | API 显示名称 |
+| description | string | 否 | API 描述说明 |
+| path | string | 是 | 访问路径 |
+| type | string | 是 | 类型，固定为 "api" |
+| method | string | 是 | 请求方法：GET、POST、ALL |
+| cache | number | 否 | 缓存时间（秒），0 表示不缓存 |
+| param_path | string | 否 | 参数验证配置文件路径 |
+| check_param | boolean | 否 | 是否校验参数 |
+| sort | number | 否 | 排序序号 |
+
+#### 2. param.json - 参数验证配置
+
+```json
+{
+  "title": "用户登录验证模型",
+  "name": "user_sign_in",
+  "filter": true,
+  "get": {
+    "query": ["account", "password", "code"],
+    "query_required": ["account"]
+  },
+  "post": {
+    "body": ["account", "password", "code", "phone"],
+    "body_required": ["account"]
+  },
+  "list": [
+    {
+      "name": "account",
+      "title": "账号",
+      "type": "string",
+      "string": {
+        "min": 5,
+        "max": 16,
+        "format": "username"
+      }
+    },
+    {
+      "name": "password",
+      "title": "密码",
+      "type": "string",
+      "string": {
+        "min": 32,
+        "max": 32,
+        "format": "password"
+      }
+    },
+    {
+      "name": "phone",
+      "title": "手机号码",
+      "type": "string",
+      "string": {
+        "format": "phone",
+        "range": [11, 11]
+      }
+    },
+    {
+      "name": "code",
+      "title": "短信验证码",
+      "type": "string"
+    }
+  ]
+}
+```
+
+**param.json 字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| title | string | 验证模型名称 |
+| name | string | 模型标识 |
+| filter | boolean | 是否启用过滤 |
+| get.query | array | GET 请求接受的查询参数 |
+| get.query_required | array | GET 请求必填参数 |
+| post.body | array | POST 请求接受的 body 参数 |
+| post.body_required | array | POST 请求必填参数 |
+| list | array | 参数验证规则列表 |
+
+**参数类型支持：**
+- `string`：字符串类型，支持 format（phone、email、username、password）、min、max、range
+- `number`：数字类型，支持 min、max、range
+- `boolean`：布尔类型
+- `array`：数组类型
+- `object`：对象类型
+
+#### 3. index.js - API 实现
+
 ```javascript
-require("mm_expand");
-const OS = require("mm_os");
-$.runPath = __dirname + $.slash;
-var os = new OS(config);
-os.run();
+/**
+ * 账户登录接口
+ * @param {Object} ctx HTTP上下文
+ * @param {Object} db 数据管理器
+ * @return {Object} 执行结果
+ */
+async function main(ctx, db) {
+  // 获取请求参数
+  var params = ctx.method === "POST" ? ctx.request.body : ctx.request.query;
+  
+  // 验证参数
+  var account = params['account'];
+  var password = params['password'];
+  
+  if (!account) {
+    return { code: 30001, message: '账号不能为空' };
+  }
+  if (!password) {
+    return { code: 30002, message: '密码不能为空' };
+  }
+  
+  // 查询用户
+  db.table = "user_account";
+  db.key = "user_id";
+  var users = await db.get({ username: account });
+  
+  if (users.length === 0) {
+    return { code: 60001, message: '用户不存在' };
+  }
+  
+  var user = users[0];
+  
+  // 验证密码
+  var pass = (password + user.salt).md5();
+  if (pass !== user.password) {
+    return { code: 30003, message: '密码错误' };
+  }
+  
+  // 设置登录状态
+  ctx.session.user = user;
+  
+  // 返回结果
+  return { 
+    code: 200, 
+    message: '登录成功',
+    data: {
+      user_id: user.user_id,
+      username: user.username,
+      nickname: user.nickname
+    }
+  };
+}
+
+exports.main = main;
 ```
 
-#### 二次开发资源
-- [二次开发快速入门指南](./doc/二次开发快速入门指南.md) - 从环境搭建到功能扩展的完整流程
-- [API参考文档](./doc/API参考文档.md) - 所有核心模块的详细API说明
-- [示例代码](./examples/) - 实用的代码示例，包括：
-  - 最小化应用示例
-  - 数据库操作示例
-  - 路由和中间件示例
-  - 插件开发示例
-
-#### 特色说明
-1.  独特的json配置文件 + js脚本的开发模式，让开发更加灵活，更加高效。
-2.  内置http请求模块、mysql、redis、mongodb模块，让请求数据和操作数据库更加简单。
-3.  适合分布式部署，支持多进程，支持负载均衡，支持集群部署。
-4.  适合微服务架构，支持服务注册与发现，支持服务调用，支持服务熔断，支持服务降级。
-5.  mm(热拔插)插件机制，可以快速扩展功能，并且支持热拔插，无需重启服务。
-6.  jwt鉴权，支持单点登录，支持多用户登录，支持多角色权限控制。
-7.  mysql数据库，支持多数据库连接，支持事务，支持分库分表。
-8.  redis缓存，支持多缓存连接，支持缓存穿透，支持缓存雪崩。
-9.  art-template模板引擎，支持多模板引擎，支持模板继承，支持模板缓存。
-10. 支持多语言，采用I18n多语言模式。
-11. 支持多协议，支持http，支持https，支持websocket，支持grpc。
-12. 支持多平台，支持windows，支持linux，支持mac。
-
-#### 参与贡献
-1.  qiuwenwu（mm_os框架创始人）
-2.  自由人网络（mm_os框架核心开发团队）
-
-#### 特点
-1.  简单易用，快速上手
-2.  高效开发，快速迭代
-3.  灵活扩展，快速定制
-4.  稳定可靠，长期维护
-5.  开源免费，社区支持
-6.  适合个人开发者，适合企业级应用
-8.  适合初创企业，中小型企业，仅需几人即可快速搭建大型网站、游戏服务端或智能物联网(AIOT)平台
-
-#### 附言
-1.  mm_os 官方网站 [www.fman.top](https://www.fman.top)
-2.  你可以访问 [https://www.fman.top/source/market](https://www.fman.top/source/market) 来了解 mm_os 上的优秀开源项目
-3.  [mm_os_server](https://www.fman.top/download) 是极为有价值开源项目，是综合评定出的优秀开源项目，具有丰富的插件、模板、挂件可用
+### 事件处理入口 (main.js)
+
+```javascript
+// 使用API管理器
+var api = $.admin.api('user_web', '网站-用户管理');
+api.call('update');
+
+/**
+ * @description 接口主函数
+ * @param {Object} ctx HTTP上下文
+ * @param {Object} db 数据管理器
+ * @return {Object} 执行结果
+ */
+async function main(ctx, db) {
+  // 设置数据库连接
+  $.push(db, $.admin.sql('sys').db(), true);
+  
+  // 使用模板引擎
+  db.tpl = new $.Tpl();
+  var bag = db.tpl.viewBag;
+  bag.path = ctx.path;
+  bag.query = ctx.query;
+  
+  // 执行API路由
+  return await api.run(ctx, db);
+}
+
+exports.main = main;
+```
+
+## 配置说明
+
+MOS 支持多种配置选项，包括：
+
+- **web**：Web 服务器配置
+- **mysql**：MySQL 数据库配置
+- **sqlite**：SQLite 数据库配置
+- **cache**：缓存配置（`way` 字段指定缓存方式：`memory`、`redis`、`mongodb`）
+- **redis**：Redis 缓存配置
+- **mongodb**：MongoDB 配置
+- **mqtt**：MQTT 服务器配置
+- **socket**：Socket 服务器配置
+
+### 配置文件示例
+
+```json
+{
+  "name": "mos",
+  "title": "服务端系统",
+  "log": {
+    "level": "debug",
+    "file": true
+  },
+  "web": {
+    "state": true,
+    "host": "0.0.0.0",
+    "port": 8000,
+    "socket": false,
+    "cos": {
+      "status": true,
+      "origin": "*"
+    },
+    "static": {
+      "state": 1,
+      "root": "./static"
+    }
+  },
+  "mysql": {
+    "host": "127.0.0.1",
+    "port": 3306,
+    "user": "root",
+    "password": "password",
+    "database": "example"
+  },
+  "cache": {
+    "way": "redis"
+  },
+  "redis": {
+    "host": "localhost",
+    "port": 6379,
+    "password": "",
+    "database": 0
+  }
+}
+```
+
+## 全局对象
+
+MOS 提供了丰富的全局对象供开发使用：
+
+### `$` 对象
+
+| 属性 | 说明 |
+|------|------|
+| `$.sql` | 数据库操作对象 |
+| `$.cache` | 缓存操作对象 |
+| `$.log` | 日志对象 |
+| `$.admin` | 管理员对象 |
+| `$.eventer` | 事件总线 |
+| `$.config` | 配置管理器 |
+| `$.Tpl` | 模板引擎类 |
+| `$.ret` | 返回结果工具 |
+| `$.run_path` | 当前运行路径 |
+
+### `$.ret` 返回工具
+
+```javascript
+// 成功返回
+return $.ret.body(data);  // { code: 200, message: 'success', data: data }
+
+// 错误返回
+return $.ret.error(code, message);  // { code: code, message: message }
+```
+
+## 开发指南
+
+1. **安装依赖**：`npm install`
+2. **开发调试**：`npm run dev`
+3. **运行测试**：`npm run test`
+
+## 许可证
+
+ISC