jax-hono 1.0.19 → 1.0.21

package/docs/jax.md

@@ -1,327 +1,329 @@
-# Jax 框架说明
-
-Jax 是当前项目内置且绑定 Hono 的轻量服务框架层，负责应用创建、路由注册、Controller/Service 基类、运行时上下文、统一响应、配置加载和代码生成。
-
-业务代码建议从 `jax` 入口导入框架核心能力：
-
-```ts
-import { ApiController, Service, createApi, config } from 'jax';
-```
-
-工具、错误、类型等分类能力建议走子入口；统一响应类型从 `jax` 主入口导出：
-
-```ts
-import { md5, createToken, escapeRegex } from 'jax/utils';
-import { JaxHttpError } from 'jax/errors';
-import type { ApiResponse } from 'jax';
-```
-
-除非是在维护 Jax 内部代码，否则不要从 `src/jax/**` 文件路径导入。
-
-## 目录结构
-
-```txt
-src/jax/
-  core/              # Hono runtime、生命周期、Controller/Service
-  middleware/        # 框架中间件
-  plugins/           # 插件定义、内置插件配置、内置插件实现
-  build/             # 代码生成/扫描注册
-  helpers/           # 框架辅助函数
-  utils/             # 更底层的纯工具
-  errors/            # 统一错误类型
-  types/             # 框架公共类型
-  .jax-hono/         # 调用项目中的自动生成注册表
-  config.ts          # 配置加载入口
-  index.ts           # 对业务侧暴露的统一入口
-  setup.ts           # 生成配置/路由/服务/模型注册表
-```
-
-## 分层边界
-
-### `base`
-
-放框架基类和请求上下文访问能力。
-
-- `Controller`：Controller 基类，提供 `this.context`、`this.ctx`、`this.state`、`this.model`、`this.service`。
-- `ApiController`：CRUD API Controller 基类，提供 `index/show/create/update/delete` 默认实现。
-- `Service`：Service 基类，提供 `this.config`、`this.model`、`this.service` 和请求上下文访问。
-
-业务 Controller 和 Service 应优先继承这些基类。
-
-### `middleware`
-
-只放框架级中间件，例如统一响应、日志、异常兜底等。
-
-业务鉴权、后台权限、企业状态校验等应放在 `src/utils`、`src/router` 或业务模块中。
-
-### `plugin`
-
-放 Jax 内置插件，例如 Mongoose 插件。
-
-插件配置参考 Egg：`src/jax/plugins/config.ts` 声明框架内置插件，业务项目通过 `src/config/plugin.ts` 显式启用或覆盖。
-
-插件形态参考 Fastify：插件模块可以导出函数，也可以通过 `definePlugin` 导出对象。
-
-插件生命周期参考 Adonis/Nuxt：对象插件支持 `setup`、`ready`、`close`。
-
-```ts
-import { definePlugin } from 'jax';
-
-export default definePlugin({
-  async setup({ config }) {
-    // 初始化插件
-  },
-  async ready() {
-    // 插件初始化后执行
-  },
-  async close() {
-    // 应用退出前清理资源
-  }
-});
-```
-
-未启用的插件不会写入调用项目的 `.jax-hono/plugins.generated.ts`，因此 `bun build` 不会解析它的运行时依赖。
-
-### `build`
-
-放代码生成和文件扫描逻辑。
-
-当前 `bun run setup` 会生成：
-
-- `.jax-hono/config.ts`
-- `.jax-hono/controllers.generated.ts`
-- `.jax-hono/middlewares.generated.ts`
-- `.jax-hono/models.generated.ts`
-- `.jax-hono/plugins.generated.ts`
-- `.jax-hono/services.generated.ts`
-- `.jax-hono/crons.generated.ts`
-- `.jax-hono/index.ts`
-
-业务代码不要手动编辑 `.jax-hono` 目录。
-
-`.jax-hono/index.ts` 是项目级 Jax 入口，会显式 import 其它生成文件、注册到 `jax-hono/core/generated`，并重新导出 `jax-hono`。使用 Bun 编译成可执行文件时，推荐用 setup 包裹 Bun 构建命令；setup 会在执行命令期间临时把入口文件里对 `jax-hono` 的导入切到项目生成入口，命令结束后恢复源码：
-
-```powershell
-bun node_modules/jax-hono/setup.ts src/index.ts -- bun build src/index.ts --compile --production --target=bun-windows-x64 --outfile dist/app.exe
-```
-
-`setup.ts` 不传入口文件时只生成 `.jax-hono`。传入入口文件但不传命令时，只检查 `.jax-hono` 入口是否可用，不修改源码。真正的编译参数仍然交给 `bun build` 自己处理。
-
-业务入口仍然写：
-
-```ts
-import { config, createApp } from 'jax-hono';
-```
-
-不要依赖 `jax-hono/generated` 这种包内目录或 Junction。`.jax-hono` 是每个调用项目自己的生成物；多个项目同时 link 到同一个 `jax-hono` 源码目录时，也不应该共享同一份生成结果。
-
-如果确实需要从非项目根目录运行未编译源码，可以设置 `JAX_HONO_GENERATED_DIR` 指向当前项目的生成目录；旧项目仍可把它设为 `generated`。编译产物仍应通过 setup 包裹构建命令，让 Bun 把 `.jax-hono` 模块打进可执行文件。
-
-### `helpers`
-
-放和 Jax 框架语义有关的辅助函数。
-
-适合放这里的例子：
-
-```ts
-normalizeRoutePath()
-getPagination()
-getClientIp()
-assertRequestContext()
-```
-
-如果函数依赖 Hono Context、Jax Context、路由、响应、Controller 生命周期等框架概念，优先放在 `helpers`。
-
-### `utils`
-
-放无框架依赖的纯工具函数。
-
-适合放这里的例子：
-
-```ts
-arrayFrom()
-escapeRegex()
-md5()
-createToken()
-isPlainObject()
-safeJsonParse()
-sleep()
-```
-
-如果函数复制到任意 TypeScript 项目都成立，可以放在 `utils`。
-
-### `errors`
-
-放框架统一错误类型。
-
-当前提供：
-
-```ts
-throw new JaxHttpError('没有权限', 403);
-```
-
-后续可以在这里扩展 `JaxValidationError`、`JaxAuthError` 等。
-
-### `response`
-
-放统一响应结构和响应构造函数。
-
-当前 API 响应格式：
-
-```ts
-{
-  code: 0,
-  msg: 'success',
-  data: {}
-}
-```
-
-失败响应格式：
-
-```ts
-{
-  code: 1,
-  msg: '错误信息'
-}
-```
-
-业务 API 中继续使用：
-
-```ts
-return c.ok(data);
-return c.fail('操作失败');
-```
-
-### `types`
-
-放框架公共类型，例如 Jax 上下文变量、状态、扩展类型。
-
-业务侧需要类型时优先从 `jax/types` 导入：
-
-```ts
-import type { JaxState } from 'jax/types';
-```
-
-## 业务代码推荐写法
-
-### Controller
-
-```ts
-import { ApiController } from 'jax';
-
-export default class CompanyController extends ApiController {
-  protected get Model() {
-    return this.model.Company;
-  }
-}
-```
-
-Controller 中推荐使用：
-
-- `this.model.Xxx` 访问模型
-- `this.service.xxx` 访问服务
-- `this.state` 访问请求状态
-- `this.context` / `this.ctx` 访问 Hono Context
-
-### Service
-
-```ts
-import { Service } from 'jax';
-
-export default class CompanyService extends Service {
-  async getCompanyInfo(companyId: string) {
-    return this.model.Company.findById(companyId).lean();
-  }
-}
-```
-
-Service 中推荐使用：
-
-- `this.config` 访问配置
-- `this.model.Xxx` 访问模型
-- `this.service.xxx` 访问其他服务
-
-不建议在业务文件里直接 import 具体 model 或 service，除非是在做类型声明、纯工具函数或非常明确的底层实现。
-
-## 什么应该放进 Jax
-
-可以放入 Jax：
-
-- 所有项目都可复用的框架能力
-- Hono/Jax 上下文相关 helper
-- Controller/Service 生命周期相关能力
-- 统一响应、错误、分页、路由注册
-- 代码生成、自动注册、配置加载
-
-不建议放入 Jax：
-
-- 企业、车辆、危废、后台账号等业务概念
-- 某个接口专用的数据转换
-- 某个业务模块专属常量
-- 和当前项目强绑定的鉴权策略
-
-简单判断：
-
-> 换一个 Jax 项目仍然成立，放 `src/jax`。只在这个业务里成立，放 `src/utils` 或具体业务模块。
-
-## 扩展规范
-
-新增框架能力时优先按下面顺序判断位置：
-
-1. 是 Hono runtime、生命周期、路由扩展或基类，放 `core`。
-2. 是框架中间件，放 `middleware`。
-3. 是插件定义、内置插件配置或内置插件实现，放 `plugins`。
-4. 是框架语义 helper，放 `helpers`。
-4. 是纯函数工具，放 `utils`。
-5. 是错误类型，放 `errors`。
-6. 是响应结构，放 `response`。
-7. 是公共类型，放 `types`。
-
-新增文件后，如果业务侧需要使用，应优先在对应子入口导出，例如 `src/jax/utils/index.ts`、`src/jax/errors/index.ts`。只有框架核心 API 才放到 `src/jax/index.ts`。
-
-内置插件配置放在 `plugins/config.ts`，内置插件实现放在 `plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只扫描已启用插件中的约定文件，不扫描未启用插件。
-
-已启用插件可以提供：
-
-- `*.controller.ts`：注册到 `controllers` 根对象
-- `*.service.ts`：注册到 `services.generated.ts`
-- `*.cron.ts`：注册到 `crons.generated.ts`，由框架统一启动/停止
-
-未启用插件不会进入生成结果，也不会让构建解析它的运行时依赖。
-
-### `cron`
-
-定时任务可以放在项目根级 `src/cron` / `src/crons` 目录，也可以放在模块或已启用插件中：
-
-```text
-src/cron/report.cron.ts
-src/modules/oss/oss-trash.cron.ts
-plugins/foo/foo-cleanup.cron.ts
-```
-
-Cron 文件导出 `defineCron()`、`cron` 或 `jobs` 即可被生成器识别：
-
-```ts
-import { defineCron } from 'jax-hono';
-
-export default defineCron({
-  name: 'daily-cleanup',
-  cron: '0 0 * * *',
-  immediate: true,
-  async run(ctx) {
-    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
-  }
-});
-```
-
-框架会在应用 ready 后统一启动定时任务，在 `app.close()` 时统一停止，不需要每个任务在入口文件手动声明。
-
-## 常用命令
-
-```bash
-bun run setup
-bun run dev
-bun run build
-```
-
-`setup` 会重新扫描并生成 Jax 注册表；新增 model、service、controller、middleware、config 后建议先执行一次。
+# Jax 框架说明
+
+Jax 是当前项目内置且绑定 Hono 的轻量服务框架层，负责应用创建、路由注册、Controller/Service 基类、运行时上下文、统一响应、配置加载和代码生成。
+
+业务代码建议从 `jax` 入口导入框架核心能力：
+
+```ts
+import { ApiController, Service, createApi, config } from 'jax';
+```
+
+工具、错误、类型等分类能力建议走子入口；统一响应类型从 `jax` 主入口导出：
+
+```ts
+import { md5, createToken, escapeRegex } from 'jax/utils';
+import { JaxHttpError } from 'jax/errors';
+import type { ApiResponse } from 'jax';
+```
+
+除非是在维护 Jax 内部代码，否则不要从 `src/jax/**` 文件路径导入。
+
+## 目录结构
+
+```txt
+src/jax/
+  core/              # Hono runtime、生命周期、Controller/Service
+  middleware/        # 框架中间件
+  plugins/           # 插件定义、内置插件配置、内置插件实现
+  build/             # 代码生成/扫描注册
+  helpers/           # 框架辅助函数
+  utils/             # 更底层的纯工具
+  errors/            # 统一错误类型
+  types/             # 框架公共类型
+  .jax-hono/         # 调用项目中的自动生成注册表
+  config.ts          # 配置加载入口
+  index.ts           # 对业务侧暴露的统一入口
+  setup.ts           # 生成配置/路由/服务/模型注册表
+```
+
+## 分层边界
+
+### `base`
+
+放框架基类和请求上下文访问能力。
+
+- `Controller`：Controller 基类，提供 `this.context`、`this.ctx`、`this.state`、`this.model`、`this.service`。
+- `ApiController`：CRUD API Controller 基类，提供 `index/show/create/update/delete` 默认实现。
+- `Service`：Service 基类，提供 `this.config`、`this.model`、`this.service` 和请求上下文访问。
+
+业务 Controller 和 Service 应优先继承这些基类。
+
+### `middleware`
+
+只放框架级中间件，例如统一响应、日志、异常兜底等。
+
+业务鉴权、后台权限、企业状态校验等应放在 `src/utils`、`src/router` 或业务模块中。
+
+### `plugin`
+
+放 Jax 内置插件，例如 Mongoose 插件。
+
+插件配置参考 Egg：`src/jax/plugins/config.ts` 声明框架内置插件，业务项目通过 `src/config/plugin.ts` 显式启用或覆盖。
+
+插件形态参考 Fastify：插件模块可以导出函数，也可以通过 `definePlugin` 导出对象。
+
+插件生命周期参考 Adonis/Nuxt：对象插件支持 `setup`、`ready`、`close`。
+
+```ts
+import { definePlugin } from 'jax';
+
+export default definePlugin({
+  async setup({ config }) {
+    // 初始化插件
+  },
+  async ready() {
+    // 插件初始化后执行
+  },
+  async close() {
+    // 应用退出前清理资源
+  }
+});
+```
+
+未启用的插件不会写入调用项目的 `.jax-hono/plugins.generated.ts`，因此 `bun build` 不会解析它的运行时依赖。
+
+### `build`
+
+放代码生成和文件扫描逻辑。
+
+当前 `bun run setup` 会生成：
+
+- `.jax-hono/config.ts`
+- `.jax-hono/controllers.generated.ts`
+- `.jax-hono/middlewares.generated.ts`
+- `.jax-hono/models.generated.ts`
+- `.jax-hono/plugins.generated.ts`
+- `.jax-hono/services.generated.ts`
+- `.jax-hono/crons.generated.ts`
+- `.jax-hono/index.ts`
+
+业务代码不要手动编辑 `.jax-hono` 目录。
+
+`.jax-hono/index.ts` 是项目级 Jax 入口，会显式 import 其它生成文件、注册到 `jax-hono/core/generated`，并重新导出 `jax-hono`。使用 Bun 编译成可执行文件时，推荐用 setup 包裹 Bun 构建命令；setup 会在执行命令期间临时把入口文件里对 `jax-hono` 的导入切到项目生成入口，命令结束后恢复源码：
+
+```powershell
+bun node_modules/jax-hono/setup.ts src/index.ts -- bun build src/index.ts --compile --production --target=bun-windows-x64 --outfile dist/app.exe
+```
+
+`setup.ts` 不传入口文件时只生成 `.jax-hono`。传入入口文件但不传命令时，只检查 `.jax-hono` 入口是否可用，不修改源码。真正的编译参数仍然交给 `bun build` 自己处理。
+
+业务入口仍然写：
+
+```ts
+import { config, createApp } from 'jax-hono';
+```
+
+不要依赖 `jax-hono/generated` 这种包内目录或 Junction。`.jax-hono` 是每个调用项目自己的生成物；多个项目同时 link 到同一个 `jax-hono` 源码目录时，也不应该共享同一份生成结果。
+
+如果确实需要从非项目根目录运行未编译源码，可以设置 `JAX_HONO_GENERATED_DIR` 指向当前项目的生成目录；旧项目仍可把它设为 `generated`。编译产物仍应通过 setup 包裹构建命令，让 Bun 把 `.jax-hono` 模块打进可执行文件。
+
+运行时会优先按当前 `cwd` 查找 `.jax-hono`，也会根据 Bun 入口脚本位置向上查找。例如 PM2 使用 `cwd: "/data/node/acs"`、`script: "acs-server/src/main.ts"` 时，框架会兼容查找 `/data/node/acs/acs-server/.jax-hono`。推荐配置仍然是把 `cwd` 指向具体项目根。
+
+### `helpers`
+
+放和 Jax 框架语义有关的辅助函数。
+
+适合放这里的例子：
+
+```ts
+normalizeRoutePath()
+getPagination()
+getClientIp()
+assertRequestContext()
+```
+
+如果函数依赖 Hono Context、Jax Context、路由、响应、Controller 生命周期等框架概念，优先放在 `helpers`。
+
+### `utils`
+
+放无框架依赖的纯工具函数。
+
+适合放这里的例子：
+
+```ts
+arrayFrom()
+escapeRegex()
+md5()
+createToken()
+isPlainObject()
+safeJsonParse()
+sleep()
+```
+
+如果函数复制到任意 TypeScript 项目都成立，可以放在 `utils`。
+
+### `errors`
+
+放框架统一错误类型。
+
+当前提供：
+
+```ts
+throw new JaxHttpError('没有权限', 403);
+```
+
+后续可以在这里扩展 `JaxValidationError`、`JaxAuthError` 等。
+
+### `response`
+
+放统一响应结构和响应构造函数。
+
+当前 API 响应格式：
+
+```ts
+{
+  code: 0,
+  msg: 'success',
+  data: {}
+}
+```
+
+失败响应格式：
+
+```ts
+{
+  code: 1,
+  msg: '错误信息'
+}
+```
+
+业务 API 中继续使用：
+
+```ts
+return c.ok(data);
+return c.fail('操作失败');
+```
+
+### `types`
+
+放框架公共类型，例如 Jax 上下文变量、状态、扩展类型。
+
+业务侧需要类型时优先从 `jax/types` 导入：
+
+```ts
+import type { JaxState } from 'jax/types';
+```
+
+## 业务代码推荐写法
+
+### Controller
+
+```ts
+import { ApiController } from 'jax';
+
+export default class CompanyController extends ApiController {
+  protected get Model() {
+    return this.model.Company;
+  }
+}
+```
+
+Controller 中推荐使用：
+
+- `this.model.Xxx` 访问模型
+- `this.service.xxx` 访问服务
+- `this.state` 访问请求状态
+- `this.context` / `this.ctx` 访问 Hono Context
+
+### Service
+
+```ts
+import { Service } from 'jax';
+
+export default class CompanyService extends Service {
+  async getCompanyInfo(companyId: string) {
+    return this.model.Company.findById(companyId).lean();
+  }
+}
+```
+
+Service 中推荐使用：
+
+- `this.config` 访问配置
+- `this.model.Xxx` 访问模型
+- `this.service.xxx` 访问其他服务
+
+不建议在业务文件里直接 import 具体 model 或 service，除非是在做类型声明、纯工具函数或非常明确的底层实现。
+
+## 什么应该放进 Jax
+
+可以放入 Jax：
+
+- 所有项目都可复用的框架能力
+- Hono/Jax 上下文相关 helper
+- Controller/Service 生命周期相关能力
+- 统一响应、错误、分页、路由注册
+- 代码生成、自动注册、配置加载
+
+不建议放入 Jax：
+
+- 企业、车辆、危废、后台账号等业务概念
+- 某个接口专用的数据转换
+- 某个业务模块专属常量
+- 和当前项目强绑定的鉴权策略
+
+简单判断：
+
+> 换一个 Jax 项目仍然成立，放 `src/jax`。只在这个业务里成立，放 `src/utils` 或具体业务模块。
+
+## 扩展规范
+
+新增框架能力时优先按下面顺序判断位置：
+
+1. 是 Hono runtime、生命周期、路由扩展或基类，放 `core`。
+2. 是框架中间件，放 `middleware`。
+3. 是插件定义、内置插件配置或内置插件实现，放 `plugins`。
+4. 是框架语义 helper，放 `helpers`。
+4. 是纯函数工具，放 `utils`。
+5. 是错误类型，放 `errors`。
+6. 是响应结构，放 `response`。
+7. 是公共类型，放 `types`。
+
+新增文件后，如果业务侧需要使用，应优先在对应子入口导出，例如 `src/jax/utils/index.ts`、`src/jax/errors/index.ts`。只有框架核心 API 才放到 `src/jax/index.ts`。
+
+内置插件配置放在 `plugins/config.ts`，内置插件实现放在 `plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只扫描已启用插件中的约定文件，不扫描未启用插件。
+
+已启用插件可以提供：
+
+- `*.controller.ts`：注册到 `controllers` 根对象
+- `*.service.ts`：注册到 `services.generated.ts`
+- `*.cron.ts`：注册到 `crons.generated.ts`，由框架统一启动/停止
+
+未启用插件不会进入生成结果，也不会让构建解析它的运行时依赖。
+
+### `cron`
+
+定时任务可以放在项目根级 `src/cron` / `src/crons` 目录，也可以放在模块或已启用插件中：
+
+```text
+src/cron/report.cron.ts
+src/modules/oss/oss-trash.cron.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+Cron 文件导出 `defineCron()`、`cron` 或 `jobs` 即可被生成器识别：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'daily-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
+框架会在应用 ready 后统一启动定时任务，在 `app.close()` 时统一停止，不需要每个任务在入口文件手动声明。
+
+## 常用命令
+
+```bash
+bun run setup
+bun run dev
+bun run build
+```
+
+`setup` 会重新扫描并生成 Jax 注册表；新增 model、service、controller、middleware、config 后建议先执行一次。