chanjs 2.7.4 → 2.7.6

package/core/App.js

@@ -0,0 +1,166 @@
+import express from "express";
+import DatabaseManager from "./Database.js";
+import { setApp } from "./registry.js";
+import { Paths } from "../utils/paths.js";
+import { loadConfig } from "./loader.js";
+import { store } from "../storage/index.js";
+import logger from "../utils/logger.js";
+import { AppError, describeError, errorExtraProps } from "./errors.js";
+import { register as registerShutdown, shutdown as runShutdown } from "../utils/signal.js";
+import { registerCoreMiddleware } from "./bootstrap/middleware.js";
+import { loadModuleRouter, loadCommonRouter } from "./bootstrap/router-loader.js";
+import { registerErrorHandler } from "./bootstrap/error-handler.js";
+import { runHooks } from "./bootstrap/hook-runner.js";
+import { loadDotEnv } from "../config/index.js";
+
+// 初始化环境变量
+loadDotEnv();
+
+/**
+ * Chan 应用核心类
+ */
+export default class Chan {
+  constructor() {
+    this.app = express();
+    this.router = express.Router();
+    this.dbManager = new DatabaseManager();
+
+    this.config = null;
+    this.paths = Paths;
+    this.db = null;
+    this.hooks = [];
+    this.server = null;
+  }
+
+  /** 完整启动流程 */
+  async start() {
+    await this.#loadConfig();
+    logger.info("[Chan] 配置加载完成");
+
+    await this.#initStore();
+    logger.info("[Chan] 缓存初始化完成");
+
+    await this.#loadDb();
+    logger.info("[Chan] 数据库加载完成");
+
+    setApp(this);
+    logger.info("[Chan] 全局应用实例注册完成");
+
+    await this.#regCoreMiddleware();
+    logger.info("[Chan] 核心中间件注册完成");
+
+    this.#setupApp();
+    await this.#loadRoutes();
+    this.#mountRouter();
+    logger.info("[Chan] 路由加载挂载完成");
+
+    this.#regErrHandler();
+    logger.info("[Chan] 全局错误中间件注册完成");
+
+    await this.#runHooks();
+    logger.info("[Chan] 启动钩子全部执行完毕");
+  }
+
+  /** 注册启动前置钩子 */
+  beforeStart(fn) {
+    if (typeof fn !== "function") {
+      throw new AppError("PARAM_INVALID", "beforeStart 参数必须为函数", 400);
+    }
+    this.hooks.push(fn);
+  }
+
+  /** 执行优雅停机流程 */
+  async shutdown() {
+    await runShutdown(this);
+  }
+
+  /**
+   * 启动 HTTP 监听服务
+   * @param {(port: number) => void} cb 启动成功回调
+   */
+  run(cb) {
+    const port = Number(this.config.PORT) || 3000;
+    this.server = this.app.listen(port, () => {
+      logger.info(`[Chan] HTTP服务启动，监听端口：${port}`);
+      cb?.(port);
+    });
+    this.server.on("error", (err) => {
+      logger.error(`[Chan] HTTP服务启动失败: ${err.message}`, err);
+    });
+    registerShutdown(this);
+  }
+
+  async #loadConfig() {
+    this.config = await loadConfig();
+  }
+
+  async #initStore() {
+    const cfg = this.config;
+    try {
+      await store.init({
+        REDIS_ENABLED: !!cfg?.REDIS_ENABLED,
+        REDIS: cfg?.REDIS ?? {}
+      });
+      if (!cfg?.REDIS_ENABLED) logger.info("[Store] Redis未开启，使用内存缓存");
+    } catch (err) {
+      logger.warn("[Store] Redis连接失败，自动降级内存缓存");
+      logger.error(`[Store] 异常信息：${describeError(err)}${errorExtraProps(err)}`, err);
+    }
+  }
+
+  async #loadDb() {
+    const dbList = this.config?.db ?? [];
+    if (!Array.isArray(dbList) || dbList.length === 0) return;
+
+    for (const [idx, dbCfg] of dbList.entries()) {
+      const dbKey = dbCfg.key ?? String(idx);
+      let conn;
+      try {
+        conn = this.dbManager.add(dbKey, dbCfg, { isDefault: idx === 0 });
+        // 首个成功连接即作为默认 this.db，避免 idx===0 失败时 this.db 恒为 null
+        if (!this.db) this.db = conn;
+      } catch (err) {
+        logger.error(`[DB] 数据库[${dbKey}]初始化失败：${describeError(err)}${errorExtraProps(err)}`, err);
+        continue;
+      }
+
+      const ok = await this.dbManager.ping(dbKey);
+      ok
+        ? logger.info(`[DB] 数据库[${dbKey}]连接正常`)
+        : logger.error(`[DB] ⚠️ 数据库[${dbKey}]连通性校验失败，请检查库服务、账号配置`);
+    }
+    logger.info(`[DB] 数据库初始化结束，共配置${dbList.length}个连接`);
+  }
+
+  async #regCoreMiddleware() {
+    await registerCoreMiddleware(this);
+  }
+
+  /**
+   * 配置 Express trust proxy
+   * 默认只信任本机回环；生产环境通过 TRUSTED_PROXIES 注入真实上游代理
+   * 切勿使用 true（信任任意来源）
+   */
+  #setupApp() {
+    const env = process.env.TRUSTED_PROXIES;
+    const trustedProxies = env ? env.split(",").map(s => s.trim()).filter(Boolean) : ["loopback"];
+    this.app.set("trust proxy", trustedProxies);
+  }
+
+  async #loadRoutes() {
+    await loadModuleRouter(this);
+    await loadCommonRouter(this);
+  }
+
+  #mountRouter() {
+    this.app.use(this.router);
+  }
+
+  #regErrHandler() {
+    registerErrorHandler(this);
+  }
+
+  async #runHooks() {
+    await runHooks(this);
+  }
+}

package/core/BaseComponent.js

@@ -0,0 +1,27 @@
+import { getApp } from "./registry.js";
+
+/**
+ * 轻量基础组件类：提供 app / config / db 快捷访问
+ * Controller / Service / Repository 统一继承此类，
+ * 不再强制绑定组件加载（Container）职责。
+ */
+export class BaseComponent {
+  /** 获取全局应用实例 */
+  get app() { return getApp(); }
+
+  /**
+   * 全局配置快捷访问
+   * 业务 Controller/Service/Repository 大量使用 `this.config.xxx` 读取配置项
+   * 统一从 app.config 取，未初始化时返回空对象避免 undefined.xxx 报错
+   */
+  get config() {
+    return this.app?.config ?? {};
+  }
+
+  /** 数据库连接快捷访问（默认连接） */
+  get db() {
+    return this.app?.db ?? null;
+  }
+}
+
+export default BaseComponent;

package/core/Container.js

@@ -0,0 +1,68 @@
+import fs from 'fs';
+import path from 'path';
+import { Paths } from '../utils/paths.js';
+import { BaseComponent } from './BaseComponent.js';
+import logger from "../utils/logger.js";
+
+const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+/**
+ * 组件容器：按需动态加载 controller/service 组件（组合模式）
+ * 继承 BaseComponent 获得 app/config/db 访问，额外提供组件加载能力
+ */
+export class Container extends BaseComponent {
+  constructor(type = 'service') {
+    super();
+    this._componentCache = new Map();
+    this._type = type;
+    this._baseDir = Paths.modulesPath;
+  }
+
+  /**
+   * 按需获取组件实例，自动缓存
+   * @param {string} moduleName 模块名
+   * @param {string} fileName 组件文件名（不含 .js）
+   */
+  async get(moduleName, fileName) {
+    const cacheKey = `${moduleName}.${fileName}`;
+    if (this._componentCache.has(cacheKey)) return this._componentCache.get(cacheKey);
+
+    try {
+      const instance = await this._loadFile(moduleName, fileName);
+      if (!instance) logger.info(`[Container] ${moduleName}/${this._type}/${fileName}.js 导出实例为空`);
+      return instance;
+    } catch (err) {
+      logger.error(`[Container] 加载组件失败 ${moduleName}/${fileName}：${err.message}`);
+      return null;
+    }
+  }
+
+  /** 物理加载文件、导入模块、安全校验 */
+  async _loadFile(moduleName, fileName) {
+    const cacheKey = `${moduleName}.${fileName}`;
+
+    if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName)) {
+      throw new Error(`非法名称 ${moduleName}/${fileName}`);
+    }
+
+    const filePath = path.resolve(this._baseDir, moduleName, this._type, `${fileName}.js`);
+    const relativePath = path.relative(this._baseDir, filePath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      throw new Error(`路径越界拦截：${filePath}`);
+    }
+
+    try {
+      await fs.promises.access(filePath, fs.constants.R_OK);
+    } catch {
+      logger.info(`[Container] 文件不存在：${moduleName}/${this._type}/${fileName}.js`);
+      return null;
+    }
+
+    const mod = await import(`file://${filePath}`);
+    const instance = mod.default;
+    this._componentCache.set(cacheKey, instance);
+    return instance;
+  }
+}
+
+export default Container;

package/core/Controller.js

@@ -0,0 +1,29 @@
+import { success, fail } from "../response/response.js";
+import Container from "./Container.js";
+
+/**
+ * 控制器基类，继承组件容器，内置统一成功/失败响应封装
+ * 响应结构 { success, code, msg, data }
+ * 错误码规范：0成功 / 1xxx业务 / 5xxx系统 / 6xxx数据库
+ */
+export default class Controller extends Container {
+  constructor() {
+    super("controller");
+  }
+
+  /**
+   * 成功返回，默认code=0
+   * @param {{data?: any, msg?: string}} opts
+   */
+  success({ data, msg = "操作成功" } = {}) {
+    return success({ data: data ?? {}, msg });
+  }
+
+  /**
+   * 失败返回，传字符串直接作为提示文案，默认code=1008
+   * @param {string | {msg?: string, code?: number}} opts
+   */
+  fail(opts = {}) {
+    return typeof opts === "string" ? fail({ msg: opts }) : fail(opts);
+  }
+}

package/core/Database.js

@@ -0,0 +1,93 @@
+import knex from "knex";
+import logger from "../utils/logger.js";
+
+const DEFAULT_NAME = "default";
+
+/**
+ * 多Knex连接管理器，统一管理连接、心跳、批量销毁
+ */
+class DatabaseManager {
+  constructor() {
+    this._connections = new Map();
+    this._defaultName = DEFAULT_NAME;
+    // 健康缓存：运行时由 error-handler 实时更新，用于鉴权层廉价区分「用户未登录」与「库挂了」
+    this._health = new Map();
+  }
+
+  /**
+   * 添加数据库连接，首个连接 / isDefault=true 自动设为默认
+   * @param {string} name 连接标识
+   * @param {object} config Knex配置
+   * @param {{isDefault?: boolean}} opts
+   * @returns {knex.Knex}
+   */
+  add(name, config, { isDefault = false } = {}) {
+    const conn = knex(config);
+    this._connections.set(name, conn);
+    if (isDefault || this._connections.size === 1) this._defaultName = name;
+    return conn;
+  }
+
+  /**
+   * 获取指定连接，不存在抛异常
+   * @param {string} [name=this._defaultName]
+   * @returns {knex.Knex}
+   */
+  get(name = this._defaultName) {
+    const conn = this._connections.get(name);
+    if (!conn) throw new Error(`Database connection "${name}" not found`);
+    return conn;
+  }
+
+  /** 批量关闭全部连接，单个失败不阻断其他 */
+  async closeAll() {
+    const results = [];
+    for (const [name, conn] of this._connections) {
+      try {
+        await conn.destroy();
+        results.push({ name, success: true });
+      } catch (err) {
+        results.push({ name, success: false, error: err.message });
+        logger.error(`[Database] 关闭连接 ${name} 失败`, err);
+      }
+    }
+    this._connections.clear();
+    logger.info(`[Database] 全部连接关闭完成，总计 ${results.length} 个`);
+    return results;
+  }
+
+  /**
+   * 心跳探测，SELECT 1 校验连通性（启动时 + 运行时按需调用）
+   * @param {string} [name=this._defaultName]
+   * @returns {boolean}
+   */
+  async ping(name = this._defaultName) {
+    const conn = this._connections.get(name);
+    if (!conn) {
+      this._health.set(name, false);
+      return false;
+    }
+    try {
+      await conn.raw("SELECT 1");
+      this._health.set(name, true);
+      return true;
+    } catch (err) {
+      this._health.set(name, false);
+      logger.error(`[Database] ping ${name} 连通校验失败`, err);
+      return false;
+    }
+  }
+
+  /** 运行时主动标记连接不可用（error-handler 捕获 DB 异常时调用） */
+  markDown(name = this._defaultName) {
+    this._health.set(name, false);
+  }
+
+  /** 运行时标记连接恢复可用（error-handler 捕获业务成功响应时调用） */
+  markUp(name = this._defaultName) {
+    this._health.set(name, true);
+  }
+}
+
+export default DatabaseManager;
+