chanjs 2.7.8 → 2.7.11

package/README.md

@@ -1,363 +1,261 @@
-# Chanjs
-
-Chanjs 是一个基于 Express 5+ 构建的轻量级 MVC 框架，完全使用 JavaScript 开发。它体现了函数式编程的概念，提供了卓越的性能、清晰的代码和易于遵循的过程，确保了高可维护性。
-
-‌ChanJS‌ 是一个基于 ‌Express 5+‌ 构建的轻量级 ‌MVC 框架‌，完全使用纯 JavaScript 开发，强调函数式编程理念，具有高性能、代码清晰、易维护等特点。
-
-## 特点
-
-### 核心架构
-- ✅ Express 5+ 原生
-- ✅ Node.js 24+
-- ✅ ES Modules (import / export)
-- ✅ 多模块 MVC 架构
-- ✅ 轻量级内核
-- ✅ 约定优于配置
-
-### 模块化
-- ✅ 多模块路由
-- ✅ 模块化 views
-- ✅ 模块化 controllers
-- ✅ 模块化 services
-- ✅ 模块化 middleware
-
-### 数据库
-- ✅ Knex.js 查询构建器
-- ✅ SQLite / MySQL / PostgreSQL
-- ✅ 连接池
-- ✅ 事务
-- ✅ 自动时间格式化
-
-### 安全能力
-- ✅ WAF 防火墙
-- ✅ XSS 防护
-- ✅ 关键词过滤
-- ✅ 请求限流
-- ✅ 路由白名单
-- ✅ Cookie 安全
-
-### 中间件生态
-- ✅ CORS
-- ✅ 请求解析
-- ✅ Cookie
-- ✅ 静态资源
-- ✅ 日志
-- ✅ Art-template 模板引擎
-
-### 高级特性
-- ✅ DI 依赖注入（Map 实现）
-- ✅ AOP 切面（before/after/error）
-- ✅ 事件系统
-- ✅ 自动加载控制器
-- ✅ 定时任务
-- ✅ WebSocket
-- ✅ 缓存系统（Redis 和 内存缓存 map 实现）
-- ✅ 分页器
-- ✅ 国际化 i18n
-- ✅ 请求验证器
-- ✅ 全局异常处理
-- ✅ 接口文档自动生成
-- ✅ 文件上传 / OSS 扩展口
-
-### 开发体验
-- ✅ 多环境配置
-- ✅ 统一响应
-- ✅ 工具函数
-
-## 约定优于配置
-
-```code
-|- app
-    |- common
-    |- helper
-    |- middleware
-    |- modules 
-        |- module1 
-            |- controller 
-            |- service 
-            |- middleware
-            |- router.js 
-        |- module2 
-            |- controller 
-            |- service 
-            |- router.js
-    |- plugins
-        |- plugin1
-            |- controller
-            |- router.js
-    |- router.js
-|- config 
-|- data
-|- doc
-|- public
-|- view
-|- app.js
-|-.env.dev
-|-.env.prd
-|- pm2.json
-|- package.json
-```
-
-
-## npm 包参考
-
-```json
-{
-  "art-template": "^4.13.4",
-  "body-parser": "^2.2.0",
-  "cookie-parser": "^1.4.7",
-  "cors": "^2.8.5",
-  "dotenv": "^17.2.1",
-  "dayjs": "^1.11.13",
-  "express": "^5.1.0",
-  "express-art-template": "^1.0.1",
-  "knex": "^3.1.0",
-  "morgan": "^1.10.0",
-  "mysql2": "^3.14.1",
-  "marked": "^17.0.3",
-  "adm-zip": "^0.5.16",
-  "bcryptjs": "^3.0.2",
-  "better-sqlite3": "^12.8.0",
-  "chanjs": "^2.6.10",
-  "cheerio": "^1.1.2",
-  "crypto-js": "^4.2.0",
-  "iconv-lite": "^0.6.3",
-  "jsonwebtoken": "^9.0.2",
-  "multer": "^2.0.2",
-  "nodemailer": "^7.0.6",
-  "qiniu": "^7.14.0",
-  "serve-favicon": "^2.5.1",
-  "xml2js": "^0.6.2",
-  "xss": "^1.0.15",
-  "zod": "^4.1.11"
-}
-```
-
-## 初始化过程
-
-```
-初始化流程：
-
-┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
-│  初始化  │───▶│ 加载配置 │───▶│ 加载数据库│───▶│ 加载扩展 │
-└─────────┘    └─────────┘    └─────────┘    └─────────┘
-                                                  │
-                    ┌─────────┐    ┌─────────┐   │
-                    │ 加载服务 │    │ 加载控制器│   │
-                    └────▲────┘    └────▲────┘   │
-                         │              │        │
-┌─────────┐    ┌─────────┐    ┌─────────┐    ┌──┴──────┐
-│ 应用路由 │◀───│加载公共路由│◀───│加载模块路由│◀───│加载中间件│
-└────┬────┘    └─────────┘    └────┬────┘    └─────────┘
-     │                             │
-     │    ┌─────────┐    ┌─────────┐    ┌─────────┐
-     └───▶│设置错误处理│───▶│beforeStart│───▶│ run启动  │
-          └─────────┘    └─────────┘    └─────────┘
-```
-
-## 核心功能
-
-### 1. 依赖注入（DI）
-
-Chanjs 提供了轻量级的依赖注入容器，支持 Service 和 Controller 的自动加载。
-
-#### 使用方式
-
-```javascript
-import { Service, Controller } from "chanjs";
-
-class UserService extends Service {
-  constructor() {
-    super("user");
-  }
-  
- 
-}
-
-class UserController extends Controller {
-  constructor() {
-    super();
-  }
-  
-  async getUser(req, res, next) {
-    
-  }
-}
-```
-
-### 2. 面向切面编程（AOP）
-
-Chanjs 提供了 AOP（面向切面编程）支持，可以在方法执行前后添加切面逻辑。
-
-#### 支持的切面类型
-
-- `before` - 方法执行前
-- `after` - 方法执行后
-- `error` - 方法执行异常时
-
-#### 使用方式
-
-```javascript
-import { aop } from "chanjs";
-
-// 注册切面函数
-aop.set("logBefore", async ({ ctx, methodName, args }) => {
-  console.log(`[Before] ${methodName} 被调用，参数:`, args);
-});
-
-aop.set("logAfter", async ({ ctx, methodName, result }) => {
-  console.log(`[After] ${methodName} 执行完成，结果:`, result);
-});
-
-aop.set("logError", async ({ ctx, methodName, error }) => {
-  console.error(`[Error] ${methodName} 执行失败:`, error);
-});
-
-// 绑定切面到实例方法
-const controller = new UserController();
-aop.wrap(controller, {
-  getUser: [
-    { type: "before", logBefore: true },
-    { type: "after", logAfter: true },
-    { type: "error", logError: true }
-  ]
-});
-
-// 调用方法时会自动执行切面
-await controller.getUser(1);
-```
-
-#### 切面配置选项
-
-```javascript
-aop.wrap(instance, {
-  methodName: [
-    { type: "before", enabled: true, customParam: "value" },
-    { type: "after", enabled: true },
-    { type: "error", enabled: false }
-  ]
-});
-```
-
-- `type` - 切面类型（before/after/error）
-- `enabled` - 是否启用该切面（默认 true）
-- 其他自定义参数会传递给切面函数
-
-### 3. 事件系统
-
-Chanjs 提供了基于 Node.js EventEmitter 的事件系统，支持应用内的事件发布订阅。
-
-#### 使用方式
-
-```javascript
-import { event } from "chanjs";
-
-// 监听事件
-event.on("user.login", (data) => {
-  console.log("用户登录:", data);
-});
-
-event.on("user.logout", (data) => {
-  console.log("用户退出:", data);
-});
-
-// 触发事件
-event.emit("user.login", { userId: 1, username: "admin" });
-
-// 移除监听器
-event.off("user.login", listener);
-
-// 移除所有监听器
-event.removeAllListeners("user.login");
-```
-
-### 4. 自动加载控制器
-
-Chanjs 提供了 `loadController` 辅助函数，可以自动加载指定模块下的所有控制器。
-
-#### 使用方式
-
-```javascript
-import { helper } from "chanjs";
-
-// 加载 member 模块下的所有控制器
-const controller = await helper.loadController("member");
-
-// 使用控制器
-controller.Member.getUser();
-controller.Comment.getComments();
-controller.Favorite.getFavorites();
-```
-
-#### 目录结构
-
-```
-member/
-  controller/
-    Member.js
-    Comment.js
-    Favorite.js
-  service/
-    Member.js
-    Comment.js
-    Favorite.js
-  router.js
-```
-
-`loadController("member")` 会自动加载 `member/controller/` 目录下的所有文件，并返回一个对象：
-
-```javascript
-{
-  Member: MemberController实例,
-  Comment: CommentController实例,
-  Favorite: FavoriteController实例
-}
-```
-
-## 运行
-
-```javascript
-import Chanjs from "chanjs";
-const chan = new Chanjs();
-
-// 前置钩子
-chan.beforeStart(fn);
-
-// 开始加载
-await chan.start();
-
-// 启动服务器
-chan.run((port) => {
-  console.log(`ChanCMS is running on ${port}`);
-});
-```
-
-## 完整示例
-
-```javascript
-import Chanjs from "chanjs";
-import { aop, event } from "chanjs";
-
-const app = new Chanjs();
-
-// 注册切面
-aop.set("logBefore", async ({ ctx, methodName, args }) => {
-  console.log(`[Before] ${methodName} 被调用`);
-});
-
-// 监听事件
-event.on("app.start", () => {
-  console.log("应用启动");
-});
-
-// 启动应用
-await app.start();
-
-// 运行
-app.run((port) => {
-  event.emit("app.start", { port });
-  console.log(`Server running on port ${port}`);
-});
-```
-
-该框架专为寻求简单与功能之间平衡的开发者设计，为构建 Web 应用程序提供了一个强大的基础。
+# ChanJS
+
+基于 Node.js + Express 5 的标准 HMVC 框架（NHMVC），纯 JavaScript（ESM）开发。模块自治 + 跨模块双通道协作，约定优于配置，开箱即用。
+
+## 特性
+
+### 核心架构
+- Express 5+ 原生
+- Node.js 22.18+
+- ES Modules（import / export）
+- 标准 HMVC 架构（模块自治 + 跨模块双通道协作）
+- 约定优于配置
+
+### 基础设施
+- **日志**：[pino](https://github.com/pinojs/pino) 高性能结构化日志
+- **请求日志**：pino-http，自动生成 requestId 贯穿全链路
+- **国际化**：[i18next](https://www.i18next.com/) 多语言支持
+- **事件总线**：EventBus，基于 Node 内置 EventEmitter
+- **定时任务**：Task，基于 [node-cron](https://github.com/node-cron/node-cron)
+- **数据库**：[Knex](https://knexjs.org/) 查询构建器，慢查询监控
+- **组件容器**：按需动态加载 controller/service，成功永久缓存、缺失不缓存
+- **优雅停机**：统一信号处理，资源按序释放
+
+### 安全能力
+- WAF 防火墙
+- XSS 防护
+- 关键词过滤
+- 请求限流
+- 路由白名单
+- Cookie 安全
+
+### 中间件生态
+- CORS
+- 请求解析（body / cookie）
+- 静态资源
+- favicon
+- 请求头注入
+- Art-template 模板引擎
+
+### 开发体验
+- 多环境配置（.env.dev / .env.prd）
+- 统一响应（success / fail）
+- Zod 参数校验中间件
+- 全局异常处理
+- 工具函数库
+
+## 目录结构
+
+```
+|- app/
+|   |- common/            # 公共路由
+|   |- helper/            # 辅助函数
+|   |- middleware/        # 应用中间件
+|   |- modules/           # 业务模块
+|   |   |- <module>/
+|   |       |- controller/
+|   |       |- service/
+|   |       |- middleware/
+|   |       |- router.js
+|   |- router.js
+|- config/                # 框架常量与环境加载
+|- data/                  # 运行数据
+|- doc/                   # 文档
+|- lang/                  # i18n 资源（zh-CN/en-US/...）
+|- public/                # 静态资源
+|- view/                  # 模板视图
+|- app.js                 # 业务入口
+|- .env.dev / .env.prd    # 环境变量
+|- pm2.json               # 进程管理
+```
+
+## 快速开始
+
+```javascript
+import Chan from "chanjs";
+
+const chan = new Chan();
+
+// 注册启动前置钩子
+chan.beforeStart(() => {
+  // 此处可注册事件监听、定时任务等
+});
+
+await chan.start();        // 加载配置、i18n、数据库、中间件、路由
+chan.run((port) => {       // 启动 HTTP 服务
+  console.log(`ChanJS running on ${port}`);
+});
+```
+
+## 核心能力
+
+### 1. 日志系统（pino）
+
+dev 环境彩色输出，prod 环境输出 JSON（pm2 捕获 stdout）。API 完全兼容旧用法。
+
+```javascript
+import logger, { createLogger } from "chanjs";
+
+// 全局日志
+logger.info("启动完成");
+logger.error("查询失败", err);   // 自动分离 Error 对象
+
+// 带模块标签的子日志
+const dbLog = createLogger("DB");
+dbLog.warn("慢查询");
+```
+
+请求日志由 pino-http 自动处理，每个请求生成唯一 `requestId`，业务中通过 `req.log` 输出带 requestId 的日志：
+
+```javascript
+// 在 Controller 中
+async getUser(req, res) {
+  req.log.info("查询用户详情");  // 自动携带 requestId
+  // ...
+}
+```
+
+### 2. 事件总线（EventBus）
+
+基于 Node 内置 EventEmitter 的轻量封装，全局单例。
+
+```javascript
+import { event, EventBus } from "chanjs";
+
+// 全局实例
+const off = event.on("user.login", (uid) => {
+  logger.info(`用户 ${uid} 登录`);
+});
+event.emit("user.login", 1001);
+off();  // 取消监听
+
+// 独立实例（隔离场景）
+const localBus = new EventBus();
+```
+
+> 详见 [doc/07-事件系统EventBus.md](./doc/07-事件系统EventBus.md)
+
+### 3. 定时任务（Task）
+
+基于 node-cron 封装，支持 cron 表达式校验、异常自动捕获、优雅停机。
+
+```javascript
+import Chan from "chanjs";
+
+const chan = new Chan();
+
+chan.beforeStart(() => {
+  // 注册定时任务（启动时自动开始）
+  chan.task.add("clear-log", "0 3 * * *", async () => {
+    await chan.db.raw("DELETE FROM logs WHERE created_at < NOW() - INTERVAL 7 DAY");
+  });
+});
+
+await chan.start();
+chan.run();
+```
+
+### 4. 国际化（i18next）
+
+启动时扫描 `lang/` 目录加载全部语言资源到内存，运行时 O(1) 查找。
+
+```
+lang/
+  zh-CN/
+    common.json    # { "user.welcome": "欢迎，{{name}}" }
+  en-US/
+    common.json    # { "user.welcome": "Welcome, {{name}}" }
+```
+
+```javascript
+import { initLang } from "chanjs";
+
+const i18n = await initLang("zh-CN");
+i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+```
+
+### 5. 数据库（Knex + 慢查询监控）
+
+多连接管理，自动慢查询与错误监控。
+
+```javascript
+// 框架启动时根据 config.db 自动注册连接
+// 业务中通过 this.db 或 getApp().db 访问默认连接
+
+// 运行时调整慢查询阈值
+chan.dbManager.setSlowThreshold(500);  // 500ms
+```
+
+### 6. 组件容器（跨模块按需获取）
+
+Controller / Service 都继承 `Container`，自带 `this.get()`，按「模块名 + 文件名」动态加载组件。
+成功永久缓存；缺失不缓存（文件新增后立即感知）。
+
+```javascript
+// 同模块获取 Service（Service 容器默认 type=service）
+const cat = await this.get("book", "BookCategory");
+
+// 跨模块获取其他模块的 Service（Controller 容器默认 type=controller，取 service 需传第三参）
+const book = await this.get("book", "Book", "service");
+const special = await this.get("cms", "Special", "service");
+```
+
+- 存在返回实例并永久缓存；缺失返回 `null`，下次实时感知。
+- 自带非法名称 / 路径越界安全校验。
+- 异步方法，需 `await`。
+- 跨模块协作优先用 `get`，避免手写 `../../` 相对路径 import。
+
+### HMVC 定位（标准实现）
+
+教科书把「Controller 嵌套调用 Controller + 运行时子请求」当作 HMVC 的标准，其实是把**实现手段**当成了标准，是片面的。
+HMVC 的本质是**分层 + 模块自治 + 跨模块复用**。Chanjs 抓住本质，支持**双通道跨模块协作**：
+
+- `await this.get("模块", "Controller")` —— 获取其他模块的 Controller（默认本容器类型）
+- `await this.get("模块", "Service", "service")` —— 获取其他模块的 Service（推荐路径）
+
+因此 Chanjs 是更贴合 HMVC 本质的**标准 HMVC 实现**，教科书把手段当标准才是过时的变体。
+
+### 7. 优雅停机
+
+统一处理 SIGTERM / SIGINT / SIGQUIT，按序释放资源：
+
+```
+HTTP 服务 → 定时任务 → 缓存存储 → 数据库连接 → 事件总线
+```
+
+单个资源关闭失败不阻断其他资源，超时强制退出。
+
+## 环境变量
+
+| 变量 | 说明 | 默认 |
+|------|------|------|
+| `NODE_ENV` | 环境（dev/prd） | dev |
+| `PORT` | HTTP 端口 | 3000 |
+| `LOCALE` | 默认语言 | zh-CN |
+| `LOG_LEVEL` | 日志级别 | dev:debug / prd:info |
+| `TRUSTED_PROXIES` | 信任代理 | loopback |
+| `SHUTDOWN_TIMEOUT` | 停机超时(ms) | 5000 |
+| `REDIS_ENABLED` | 启用 Redis | false |
+
+## 依赖
+
+### 运行时依赖
+- express ^5.2.1
+- knex ^3.2.10
+- pino ^9.5.0
+- pino-http ^10.3.0
+- i18next ^24.2.0
+- node-cron ^3.0.3
+- art-template ^4.13.4
+- mysql2 ^3.22.3
+- ioredis ^5.4.6
+
+### 开发依赖
+- pino-pretty ^11.3.0
+
+### 可选 Peer 依赖
+- zod ^4.4.3（参数校验）
+
+## License
+
+ISC

package/config/index.js

@@ -7,7 +7,8 @@ import { Paths } from "../utils/paths.js";
  * 框架运行默认常量
  * 1. 优雅停机强制退出超时(ms)
  * 2. 请求体最大限制
- * 3. 单条beforeStart启动钩子超时阈值(ms)
+ * 3. 单条 beforeStart 启动钩子超时阈值(ms)
+ * 4. 数据库慢查询阈值(ms)，超过则记 warn 日志
  */
 
 export const SHUTDOWN_TIMEOUT = 5000;
@@ -16,6 +17,7 @@ export const BODY_LIMIT = "10mb";
 
 export const HOOK_TIMEOUT = 10000;
 
+export const SLOW_THRESHOLD = 200;
 
 /**
  * @description {string}
@@ -38,4 +40,4 @@ export function loadDotEnv() {
   if (fs.existsSync(envPath)) {
     dotenv.config({ path: envPath });
   }
-}
+}