chanjs-hono

v1.0.4

Published

a month ago

chanjs-hono 基于 Hono + Drizzle ORM 研发的轻量级 MVC 框架，API 镜像 chanjs，支持 pgsql / mysql / sqlite。

0High
0Medium
0Low

yanyutao

chanjs-hono hono mvc hono drizzle hono postgres hono mysql hono sqlite nodejs mvc

ChanJS-Hono

ChanJS 的 Hono 高性能分支，基于 Hono + Drizzle ORM 构建的标准 HMVC（NHMVC）后端框架，原生 ESM 纯 JavaScript 开发。 API 与 chanjs 保持一致，以模块自治 + 双通道跨模块协作为核心，约定优于配置，开箱即用，拒绝冗余复杂。

设计哲学

大道至简。 优秀的开发工具，应当化繁为简。ChanJS-Hono 摒弃过度设计与沉重抽象，回归纯粹 JavaScript，用最少的心智负担交付稳定高效的业务能力。

核心亮点

⚡ 超快路由：Hono 高性能路由引擎，零依赖内置中间件（cors / cookie / jwt / logger）
🗄️ 三库统一：Drizzle ORM 官方支持 PostgreSQL / MySQL / SQLite，配置切换零代码改动
🪶 轻量精简：API 与目录结构镜像 chanjs，无额外心智负担、低侵入、上手门槛低
🔌 边缘适配：app.fetch 纯函数，天然适配边缘运行 / Serverless 环境
🛡️ 安全可控：内置多层防护能力，降低业务安全开发成本

特性

核心架构

原生基于 Hono + @hono/node-server，app.fetch 支持 Serverless / 边缘部署
最低运行环境 Node.js 22.0+
全量 ES Modules（import / export）
标准 HMVC 架构：模块自治 + 双通道跨模块协作
约定优于配置，目录结构与 chanjs 完全一致

基础设施

高性能日志：Pino 结构化日志输出
国际化多语言：i18next，内存高速语言查找
全局事件总线：轻量封装 Node.js EventEmitter，解耦业务事件
定时任务调度：node-cron，自带异常捕获、停机安全回收
数据库层：Drizzle ORM 三库统一（postgres-js / mysql2 / better-sqlite3），内置慢查询监控告警
按需组件容器：Controller/Service 动态懒加载，成功实例永久缓存；缺失模块不缓存，修改文件即时生效
优雅停机：统一信号监听，资源有序释放（HTTP → Task → 缓存 → DB → 事件总线），超时强制退出

内置安全能力

JWT 令牌签发 / 校验 / 吊销
AES-256-GCM 加解密
接口请求限流
IP 网关（isTrustedIp / getClientIp）
XSS 过滤 / 敏感关键词检测

开箱即用基础设施

统一响应体（success / fail / frame 适配器）
业务状态码体系（CODE / getCodeMsg / CODE_*）
zod 参数校验中间件（validate / validateAll）
全局异常捕获兜底（AppError 体系）
多环境配置隔离（.env.dev / .env.prd）
Redis ⇄ 内存双后端缓存熔断降级
内置通用工具函数库（tree / pages / request / file / time 等）

目录结构

|- 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    # 环境配置文件

快速开始

npm install chanjs-hono --save

import Chan from "chanjs-hono";

const chan = new Chan();

// 注册启动前置钩子（事件、定时任务等初始化）
chan.beforeStart(() => {
});

await chan.start();        // 加载配置、i18n、数据库、中间件、路由
chan.run((port) => {       // 启动 HTTP 服务
  console.log(`ChanJS-Hono running on ${port}`);
});

核心能力详解

1. 日志系统（Pino）

开发环境彩色控制台输出；生产环境输出 JSON 结构化日志，适配 PM2 采集。API 向下完全兼容。

import logger, { createLogger } from "chanjs-hono";

// 全局日志实例
logger.info("启动完成");
logger.error("查询失败", err);   // 自动识别 Error 对象

// 创建带业务标签的子日志
const dbLog = createLogger("DB");
dbLog.warn("慢查询");

2. 事件总线（EventBus）

基于 Node.js 原生 EventEmitter 封装的全局单例事件中心，用于业务解耦。

import { event, EventBus } from "chanjs-hono";

// 使用全局事件实例
const off = event.on("user.login", (uid) => {
  logger.info(`用户 ${uid} 登录`);
});
event.emit("user.login", 1001);
off();  // 解绑监听

// 创建独立隔离的事件实例
const localBus = new EventBus();

3. 定时任务（Task）

基于 node-cron 封装，内置 cron 表达式校验、任务异常捕获、优雅停机回收。

import Chan from "chanjs-hono";

const chan = new Chan();

chan.beforeStart(() => {
  // 注册定时任务，框架启动后自动运行
  chan.task.add("clear-log", "0 3 * * *", async () => {
    await chan.db.run(sql`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}}" }

import { initLang } from "chanjs-hono";

const i18n = await initLang("zh-CN");
i18n.t("user.welcome", { name: "张三" });  // → "欢迎，张三"

5. 数据库（Drizzle ORM · 三库统一）

支持 PostgreSQL / MySQL / SQLite 三库统一连接管理，自动开启慢查询与 SQL 异常监控。

// 框架启动自动读取 config.db 注册数据库连接（数组首个连接为默认连接）
// 业务代码内可通过 this.db / getApp().db 获取默认连接

// 运行时动态调整慢查询告警阈值（毫秒）
chan.dbManager.setSlowThreshold(500);

// config 配置示例（任选一库）
export default {
  db: [
    {
      key: "primary",          // 连接标识（多库时用于切换）
      driver: "postgres",      // postgres / mysql / sqlite
      host: "127.0.0.1",
      port: 5432,
      user: "root",
      password: "***",
      database: "chancms",
      pool: { max: 10 },
    },
    // SQLite 只需指定文件路径：
    // { key: "lite", driver: "sqlite", file: "data/chancms.db" }
  ],
};

6. 组件容器 · 双通道跨模块调用

Controller / Service 继承容器基类，内置 this.get() 方法，通过「模块名 + 组件名」动态加载跨模块业务组件。

加载成功后实例永久缓存；组件文件缺失不缓存，新增文件无需重启即可识别。

// 同一模块调用 Service
const cat = await this.get("book", "BookCategory");

// 跨模块调用 Service（推荐，HMVC 双通道-服务通道）
const book = await this.get("book", "Book", "service");
const special = await this.get("cms", "Special", "service");

返回实例或 null，异步调用必须 await
内置名称校验、路径越界安全防护
跨模块业务复用优先使用容器调用，摒弃超长相对路径 import

HMVC 标准实现说明

传统教程常将「控制器嵌套发起子 HTTP 请求」当作 HMVC 的标准，该方式混淆了实现手段和架构本质。

HMVC 的核心 = 分层解耦 + 模块自治 + 跨模块业务复用。

ChanJS-Hono 提供双通道协作模式，回归 HMVC 本质：

控制器通道：await this.get("模块", "Controller")
服务通道（推荐）：await this.get("模块", "Service", "service")

7. Hono Handler 序列化适配（frame）

本框架特色：业务 handler 的返回值统一由 frame 适配器转成 Hono Response。

import { frame } from "chanjs-hono";

// 返回 Response：直接透传
// 返回 { success, code, msg, data }：序列化为 JSON（HTTP 200，业务码在 body）
// 返回其他对象：包裹为 data 返回
const route = frame(async (c) => {
  return { data: { id: 1 }, msg: "成功" };
});

8. 优雅停机

统一监听 SIGTERM / SIGINT / SIGQUIT 退出信号，按顺序逐级释放资源：

HTTP 服务 → 定时任务 → 缓存存储 → 数据库连接 → 事件总线

单个资源关闭失败不会阻断其余回收流程，超时后进程强制退出。

环境变量配置

| 变量 | 说明 | 默认值 | | --- | --- | --- | | NODE_ENV | 运行环境标识(dev/prd) | dev | | PORT | HTTP 监听端口 | 3000 | | HOST | 监听地址 | 0.0.0.0 | | LOCALE | 默认语言 | zh-CN | | LOG_LEVEL | 日志输出级别 | dev:debug / prd:info | | SHUTDOWN_TIMEOUT | 优雅停机超时时间(ms) | 5000 | | REDIS_ENABLED | 是否开启 Redis | false |

项目依赖清单

运行依赖

hono ^4.7.0
@hono/node-server ^1.14.0
drizzle-orm ^0.44.0
pino ^9.5.0
i18next ^24.2.0
node-cron ^3.0.3
art-template ^4.13.4
ioredis ^5.4.2
zod ^3.24.0
dayjs ^1.11.13
dotenv ^16.4.7
数据库驱动（按所选数据库安装）：postgres ^3.4.5 / mysql2 ^3.12.0 / better-sqlite3 ^12.2.0

可选 Peer 依赖

zod（参数校验）

SQLite 驱动为 Node.js ≥22.5 内置的 node:sqlite，运行时零第三方依赖、无 native 编译；低版本 Node 下 pg/mysql 不受影响，仅使用 sqlite 时报明确错误。

ChanJS 标准版本

chanjs 为 ChanJS 标准版本，基于 Express 5 + Knex 构建，API 与本框架保持一致。

npm install chanjs

详细文档

| 文档 | 说明 | | --- | --- | | doc/00-README.md | 安装 / 目录结构 / 技术选型对比 | | doc/01-架构设计与Chanjs差异.md | 逐条分析 chanjs 不足 + 本框架改进方案 | | doc/02-数据库适配.md | pg / mysql / sqlite 三库适配设计与迁移 | | doc/03-核心类.md | BaseComponent / Controller / Service / Repository 全部方法与用法 | | doc/04-响应与错误.md | 统一响应、业务状态码、错误体系 | | doc/05-安全模块.md | JWT / AES / 限流 / IP 网关 / XSS / 敏感词 | | doc/06-存储与缓存.md | Store 统一门面、内存 LRU、Redis ⇄ 内存双后端熔断降级 | | doc/07-工具与校验.md | zod 校验中间件 + 时间/文件/HTML/请求/树/分页等工具函数 | | doc/08-应用生命周期.md | Chan 启动流程、中间件/路由、钩子、优雅停机、Paths | | doc/09-事件-定时任务-国际化.md | 事件总线 / Task 定时任务 / i18next 国际化 |

文档 & 生态资源

ChanJS官网文档：ChanJS
ChanJS-Hono官网文档：ChanJS-Hono
ChanJS-cli官方脚手架：ChanJS-cli
ChanCMS官方开源 CMS：ChanCMS

开源协议

ISC