chanjs 2.7.3 → 2.7.5

package/USAGE.md

@@ -0,0 +1,533 @@
+# ChanJS 使用文档
+
+> 基于 Express 5 的轻量级 Node.js MVC 框架
+
+## 目录
+
+- [快速开始](#快速开始)
+- [项目结构](#项目结构)
+- [配置说明](#配置说明)
+- [Controller 控制器](#controller-控制器)
+- [Service 服务层](#service-服务层)
+- [Repository 数据仓库](#repository-数据仓库)
+- [路由定义](#路由定义)
+- [中间件](#中间件)
+- [参数校验](#参数校验)
+- [响应封装](#响应封装)
+- [错误处理](#错误处理)
+- [安全机制](#安全机制)
+- [存储系统](#存储系统)
+- [日志系统](#日志系统)
+- [工具函数](#工具函数)
+- [启动钩子](#启动钩子)
+- [优雅停机](#优雅停机)
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install chanjs
+```
+
+### 入口文件
+
+```javascript
+// app.js
+import Chan from "chanjs";
+
+const chan = new Chan();
+await chan.start();
+chan.run(port => {
+  console.log(`服务启动在端口 ${port}`);
+});
+```
+
+### 启动
+
+```bash
+# 开发环境
+NODE_ENV=dev node app.js
+
+# 生产环境
+NODE_ENV=prd node app.js
+```
+
+---
+
+## 项目结构
+
+```
+project/
+├── app.js                    # 入口文件
+├── router.js                 # 公共路由（可选）
+├── config/
+│   └── index.js              # 全局配置
+├── public/
+│   └── favicon.ico           # 网站图标
+├── app/
+│   ├── modules/              # 业务模块
+│   │   ├── web/              # 前端页面模块
+│   │   │   ├── controller/   # 控制器
+│   │   │   ├── service/      # 服务层
+│   │   │   └── router.js     # 模块路由
+│   │   └── api/              # API 模块
+│   │       ├── controller/
+│   │       ├── service/
+│   │       └── router.js
+│   ├── common/               # 公共资源
+│   ├── helper/               # 辅助工具
+│   └── extend/               # 扩展
+├── .env.dev                  # 开发环境变量
+└── .env.prd                  # 生产环境变量
+```
+
+---
+
+## 配置说明
+
+### config/index.js
+
+```javascript
+export default {
+  // 应用信息
+  APP_NAME: "MyApp",
+  APP_VERSION: "1.0.0",
+  PORT: 3000,
+  NODE_ENV: process.env.NODE_ENV || "dev",
+
+  // 业务模块列表（路由按此顺序加载，web 模块自动后置）
+  modules: ["api", "web"],
+
+  // 数据库配置（支持多库）
+  db: [
+    {
+      key: "default",
+      client: "mysql2",
+      connection: {
+        host: process.env.DB_HOST || "127.0.0.1",
+        port: process.env.DB_PORT || 3306,
+        user: process.env.DB_USER || "root",
+        password: process.env.DB_PASSWORD || "",
+        database: process.env.DB_NAME || "mydb",
+      },
+      pool: { min: 2, max: 10 },
+    },
+  ],
+
+  // Redis 配置（可选）
+  REDIS_ENABLED: process.env.REDIS_ENABLED === "true",
+  REDIS: {
+    host: process.env.REDIS_HOST || "127.0.0.1",
+    port: process.env.REDIS_PORT || 6379,
+    password: process.env.REDIS_PASSWORD || "",
+    db: 0,
+  },
+
+  // JWT 密钥
+  JWT_SECRET: process.env.JWT_SECRET || "your-secret-key",
+
+  // Cookie 签名密钥
+  cookieKey: process.env.COOKIE_KEY || "cookie-secret",
+
+  // 分页配置
+  PAGE_SIZE: 20,
+  LIMIT_MAX: 300,
+
+  // 请求体大小限制
+  BODY_LIMIT: "10mb",
+
+  // 静态资源配置
+  statics: [
+    { prefix: "/static", dir: "public/static", maxAge: 86400000 },
+  ],
+
+  // 模板视图目录
+  views: ["app/modules/web/view"],
+
+  // CORS 跨域配置
+  cors: {
+    origin: "*",
+    methods: ["GET", "POST", "PUT", "DELETE"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    credentials: false,
+  },
+
+  // WAF 防火墙配置
+  waf: {
+    enabled: true,
+    rateLimit: {
+      windowMs: "1m",      // 时间窗口
+      max: 60,             // 窗口内最大请求数
+      ignorePaths: [],     // 白名单路径
+    },
+    block: {
+      BLOCK_DURATION: 30 * 60 * 1000,   // 封禁时长 30 分钟
+      STRIKE_THRESHOLD: 3,              // 命中次数阈值
+      STRIKE_WINDOW: 60 * 60 * 1000,    // 计数窗口
+    },
+  },
+
+  // 日志配置
+  logger: {
+    level: "chancms",  // chancms | combined | common | dev | short | tiny
+  },
+};
+```
+
+### 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `NODE_ENV` | 运行环境 | `dev` |
+| `ENV_FILE` | 自定义环境文件 | `.env.dev` / `.env.prd` |
+| `DB_HOST` | 数据库地址 | `127.0.0.1` |
+| `DB_PORT` | 数据库端口 | `3306` |
+| `DB_USER` | 数据库用户 | `root` |
+| `DB_PASSWORD` | 数据库密码 | - |
+| `DB_NAME` | 数据库名 | - |
+| `REDIS_ENABLED` | 是否启用 Redis | `false` |
+| `REDIS_HOST` | Redis 地址 | `127.0.0.1` |
+| `REDIS_PORT` | Redis 端口 | `6379` |
+| `REDIS_PASSWORD` | Redis 密码 | - |
+| `JWT_SECRET` | JWT 签名密钥 | - |
+| `COOKIE_KEY` | Cookie 签名密钥 | - |
+| `TRUSTED_PROXIES` | 信任代理 IP（逗号分隔） | `loopback` |
+| `EXPOSE_ERR_DETAIL` | 是否暴露错误详情 | `false` |
+| `DEBUG_TOKEN` | 调试令牌（生产环境查看错误详情） | - |
+| `LOG_LEVEL` | 日志级别 | `debug` (dev) / `info` (prd) |
+| `LOG_FILE` | 日志文件路径（仅 dev） | - |
+| `AES_SALT` | AES 加密盐值 | - |
+| `CF_ENABLED` | 是否启用 Cloudflare IP 解析 | `false` |
+
+---
+
+## Controller 控制器
+
+控制器继承自 `Controller` 基类，内置响应封装。
+
+```javascript
+// app/modules/api/controller/UserController.js
+import { Controller } from "chanjs";
+
+class UserController extends Controller {
+  // 获取用户列表
+  async list(req, res) {
+    const { page = 1, pageSize = 10 } = req.query;
+    const result = await this.getUserList(page, pageSize);
+    return res.json(this.success({ data: result }));
+  }
+
+  // 创建用户
+  async create(req, res) {
+    const { name, email } = req.body;
+    if (!name) {
+      return res.json(this.fail("用户名不能为空"));
+    }
+    const user = await this.createUser({ name, email });
+    return res.json(this.success({ data: user, msg: "创建成功" }));
+  }
+
+  // 访问配置和数据库
+  async info(req, res) {
+    const config = this.config;   // 全局配置
+    const db = this.db;           // 默认数据库连接
+    const paths = this.paths;     // 路径配置
+    const app = this.app;         // 全局应用实例
+    return res.json(this.success({ data: { config, paths } }));
+  }
+
+  // 加载其他模块的 service
+  async loadData(req, res) {
+    const articleService = await this.get("api", "ArticleService");
+    const data = await articleService.getArticles();
+    return res.json(this.success({ data }));
+  }
+}
+
+export default new UserController();
+```
+
+### Controller 方法
+
+| 方法 | 说明 |
+|------|------|
+| `this.success({ data, msg })` | 成功响应 `{ success: true, code: 0, msg, data }` |
+| `this.fail(msg)` | 失败响应（字符串直接作为提示文案） |
+| `this.fail({ msg, code, data })` | 失败响应（对象形式） |
+| `this.config` | 全局配置 |
+| `this.db` | 默认数据库连接 |
+| `this.paths` | 路径配置 |
+| `this.app` | 全局应用实例 |
+| `this.get(moduleName, fileName)` | 加载其他组件 |
+
+---
+
+## Service 服务层
+
+Service 用于封装业务逻辑，可注入多个 Repository 进行跨表事务编排。
+
+```javascript
+// app/modules/api/service/UserService.js
+import { Service } from "chanjs";
+
+class UserService extends Service {
+  async getUserWithArticles(userId) {
+    const userRepo = await this.get("api", "UserRepository");
+    const articleRepo = await this.get("api", "ArticleRepository");
+
+    const user = await userRepo.findById(userId);
+    const articles = await articleRepo.all({
+      query: { user_id: userId },
+      sort: { created_at: "desc" },
+    });
+
+    return { user: user.data, articles: articles.data };
+  }
+}
+
+export default new UserService();
+```
+
+---
+
+## Repository 数据仓库
+
+Repository 封装通用 CRUD 操作，继承自 `Container`。
+
+```javascript
+// app/modules/api/service/UserRepository.js
+import { Repository } from "chanjs";
+
+class UserRepository extends Repository {
+  constructor() {
+    super("users");  // 绑定表名
+  }
+
+  // 自定义查询方法
+  async findByEmail(email) {
+    return this.findOne({ query: { email } });
+  }
+
+  // 复杂查询
+  async searchUsers(keyword, page = 1) {
+    return this.query({
+      current: page,
+      pageSize: 10,
+      query: {
+        name: { $like: `%${keyword}%` },
+        status: 1,
+      },
+      sort: { created_at: "desc" },
+      field: ["id", "name", "email", "created_at"],
+    });
+  }
+}
+
+export default new UserRepository();
+```
+
+### 构造函数
+
+```javascript
+super(tableName, dbName?, opts?)
+```
+
+| 参数 | 说明 |
+|------|------|
+| `tableName` | 表名 |
+| `dbName` | 数据库连接名（多库时使用） |
+| `opts.dateFields` | 自定义日期字段列表 |
+
+### 内置方法
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `all({ query, sort, fields, limit })` | 查询全部 | `{ success, code, msg, data }` |
+| `find({ query, sort, fields, limit, offset })` | 分页偏移查询 | 同上 |
+| `findOne({ query, fields })` | 查询单条 | 同上 |
+| `findById(id, { fields })` | 根据 ID 查询 | 同上 |
+| `insert(data)` | 单条插入 | `{ success, code, msg, data: { insertId, affectedRows } }` |
+| `insertMany(records)` | 批量插入 | 同上 |
+| `del(query)` / `delete(query)` | 条件删除 | `{ success, code, msg, data: { affectedRows } }` |
+| `deleteById(id)` | 根据 ID 删除 | 同上 |
+| `deleteMany(ids)` | 批量删除 | 同上 |
+| `updateByQuery({ query, data })` | 条件更新 | 同上 |
+| `updateById(id, data)` | 根据 ID 更新（返回更新后数据） | `{ success, code, msg, data }` |
+| `updateMany(updates)` | 事务批量更新 | `{ success, code, msg, data: { affectedRows } }` |
+| `query({ current, pageSize, query, sort, field })` | 标准分页 | `{ success, code, msg, data: { list, total, current, pageSize, totalPages } }` |
+| `count(query)` | 统计行数 | `{ success, code, msg, data: { count } }` |
+| `exists(query)` | 判断存在 | `{ success, code, msg, data: { exists } }` |
+| `join({ joinTable, localField, foreignField, fields, query, sort })` | 联表查询 | `{ success, code, msg, data }` |
+| `stats()` | 统计总数+今日新增 | `{ success, code, msg, data: { total, today } }` |
+
+### 查询操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$like` | 模糊匹配 | `{ name: { $like: "%张%" } }` |
+| `$gt` | 大于 | `{ age: { $gt: 18 } }` |
+| `$gte` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lt` | 小于 | `{ age: { $lt: 60 } }` |
+| `$lte` | 小于等于 | `{ age: { $lte: 60 } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 0 } }` |
+| `$in` | 包含 | `{ id: { $in: [1, 2, 3] } }` |
+| `$null` | 为空 | `{ deleted_at: { $null: true } }` |
+| `$notNull` | 不为空 | `{ email: { $notNull: true } }` |
+
+### 受保护的方法
+
+| 方法 | 说明 |
+|------|------|
+| `this._checkDB()` | 前置数据库校验 |
+| `this._buildBaseQuery({ query, sort, fields })` | 统一构建查询实例 |
+
+---
+
+## 路由定义
+
+### 模块路由
+
+```javascript
+// app/modules/api/router.js
+import { Router } from "express";
+import { getApp } from "chanjs";
+import UserController from "./controller/UserController.js";
+
+export default async (app, router, config) => {
+  // 基础路由
+  router.get("/api/users", UserController.list.bind(UserController));
+  router.post("/api/users", UserController.create.bind(UserController));
+
+  // 带参数的路由
+  router.get("/api/users/:id", async (req, res) => {
+    const userRepo = await getApp().dbManager.get("default");
+    // ...
+  });
+
+  // 使用中间件
+  router.post("/api/users/update", authMiddleware, UserController.update.bind(UserController));
+};
+```
+
+### 公共路由
+
+```javascript
+// router.js（项目根目录）
+export default async (app, router, config) => {
+  router.get("/", (req, res) => {
+    res.render("index", { title: "首页" });
+  });
+};
+```
+
+---
+
+## 中间件
+
+### 内置中间件
+
+框架自动注册以下中间件（顺序固定）：
+
+1. **WAF 前置** — IP/关键词/限流/封禁检测
+2. **Favicon** — 网站图标
+3. **静态资源** — 配置目录的静态文件服务
+4. **Cookie** — Cookie 解析与签名
+5. **Body 解析** — JSON/URL-encoded/XML
+6. **WAF Body** — 请求体关键词/XSS 检测
+7. **CORS** — 跨域处理
+8. **日志** — 请求日志（morgan）
+9. **模板引擎** — art-template
+10. **响应头** — 安全头设置
+
+### 自定义中间件
+
+```javascript
+// 在路由中使用
+import { validate, helper } from "chanjs";
+
+router.post("/api/users", 
+  validate(userSchema),  // zod 校验
+  UserController.create.bind(UserController)
+);
+```
+
+---
+
+## 参数校验
+
+基于 **zod** 的声明式校验。
+
+```javascript
+import { z } from "zod";
+import { validate, validateAll } from "chanjs";
+
+// 单来源校验
+const createUserSchema = z.object({
+  name: z.string().min(1, "用户名不能为空"),
+  email: z.string().email("邮箱格式不正确"),
+  age: z.number().int().min(0).max(150).optional(),
+});
+
+router.post("/api/users", 
+  validate(createUserSchema, "body"),
+  UserController.create.bind(UserController)
+);
+
+// 多来源校验
+router.put("/api/users/:id",
+  validateAll({
+    params: z.object({ id: z.number().int().positive() }),
+    body: createUserSchema.partial(),
+  }),
+  UserController.update.bind(UserController)
+);
+```
+
+校验失败自动抛出 `ValidationError`，由全局错误处理器统一返回 422 响应。
+
+---
+
+## 响应封装
+
+### 统一响应格式
+
+```javascript
+{
+  success: true/false,
+  code: 0,          // 业务码：0成功，1xxx业务错误，5xxx系统错误，6xxx数据库错误
+  msg: "操作成功",
+  data: {}
+}
+```
+
+### 业务码规范
+
+| 分段 | 类型 | 示例 |
+|------|------|------|
+| 0 | 成功 | 操作成功 |
+| 1xxx | 通用业务错误 | 认证失败(1001)、令牌过期(1002)、权限不足(1003)、资源不存在(1004)、参数无效(1006) |
+| 5xxx | 系统错误 | 系统内部错误(5001)、服务繁忙(5002) |
+| 6xxx | 数据库错误 | 连接失败(6001)、访问拒绝(6002)、操作超时(6007) |
+
+### 在 Controller 中使用
+
+```javascript
+// 成功
+return res.json(this.success({ data: userList, msg: "查询成功" }));
+
+// 失败（字符串简写）
+return res.json(this.fail("用户名已存在"));
+
+// 失败（对象形式）
+return res.json(this.fail({ msg: "参数错误", code: 1006, data: { field: "email" } }));
+```
+
+### 独立使用（非 Controller 场景）
+
+```javascript
+import { success, fail } from "chanjs";
+
+const ok = success({ data: { id: 1 }, msg: "创建成功" });

package/config/index.js

@@ -1,10 +1,41 @@
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { Paths } from "../utils/paths.js";
+
+/**
+ * 框架运行默认常量
+ * 1. 优雅停机强制退出超时(ms)
+ * 2. 请求体最大限制
+ * 3. 单条beforeStart启动钩子超时阈值(ms)
+ */
+
+export const SHUTDOWN_TIMEOUT = 5000;
+
+export const BODY_LIMIT = "10mb";
+
+export const HOOK_TIMEOUT = 10000;
+
+
 /**
- * 配置模块入口
- * 导出所有配置相关的内容
+ * @description {string}
+ * @description 环境文件加载工具 获取当前生效的环境文件名
+ * 优先级：进程自定义ENV_FILE > NODE_ENV区分dev/prd
  */
+export function getEnvFilePath() {
+  return process.env.ENV_FILE || (process.env.NODE_ENV === "dev" ? ".env.dev" : ".env.prd");
+}
 
-import { CODE, DB_ERROR } from "./code.js";
-import { Paths } from "./paths.js";
+/**
+ * @description {void}
+ * @description 环境文件加载工具 加载对应环境env文件，文件不存在静默跳过，不阻断启动
+ */
+export function loadDotEnv() {
+  const envName = getEnvFilePath();
+  const envPath = path.resolve(Paths.rootPath, envName);
 
-export { CODE, DB_ERROR, Paths };
-export default { CODE, DB_ERROR, Paths };
+  // 文件存在才加载，不存在直接跳过
+  if (fs.existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+  }
+}