jax-hono 1.0.0

package/docs/jax.md

@@ -0,0 +1,272 @@
+# 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/             # 框架公共类型
+  generated/         # 自动生成的注册表
+  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() {
+    // 应用退出前清理资源
+  }
+});
+```
+
+未启用的插件不会写入 `src/jax/generated/plugins.generated.ts`，因此 `bun build` 不会解析它的运行时依赖。
+
+### `build`
+
+放代码生成和文件扫描逻辑。
+
+当前 `bun run setup` 会生成：
+
+- `src/jax/generated/config.ts`
+- `src/jax/generated/controllers.generated.ts`
+- `src/jax/generated/middlewares.generated.ts`
+- `src/jax/generated/models.generated.ts`
+- `src/jax/generated/plugins.generated.ts`
+- `src/jax/generated/services.generated.ts`
+
+业务代码不要手动编辑 `generated` 目录。
+
+### `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`。
+
+内置插件配置放在 `src/jax/plugins/config.ts`，内置插件实现放在 `src/jax/plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只读取插件配置，不扫描插件目录。
+
+## 常用命令
+
+```bash
+bun run setup
+bun run dev
+bun run build
+```
+
+`setup` 会重新扫描并生成 Jax 注册表；新增 model、service、controller、middleware、config 后建议先执行一次。

package/helpers/config.ts

@@ -0,0 +1,23 @@
+import type { JaxConfig } from '../types/config';
+
+type PlainConfig = Record<string, unknown>;
+
+export type PluginConfigItem =
+  | false
+  | {
+      enable?: boolean;
+      package?: string;
+      options?: unknown;
+    };
+
+export type PluginConfig = Record<string, PluginConfigItem>;
+
+export function defineConfig<TProjectConfig extends PlainConfig = PlainConfig>(
+  config: Partial<JaxConfig & TProjectConfig>
+) {
+  return config;
+}
+
+export function definePluginConfig<TPluginConfig extends PluginConfig>(config: TPluginConfig) {
+  return config;
+}

package/helpers/crud.ts

@@ -0,0 +1,30 @@
+import { normalizeRoutePath } from './route';
+import type { Handler, Hono } from 'hono';
+
+export type JaxCrudController = {
+  index: Handler;
+  show: Handler;
+  create: Handler;
+  update: Handler;
+  delete?: Handler;
+  destroy?: Handler;
+};
+
+export function registerCrudRoutes(app: Hono, path: string, controller: JaxCrudController) {
+  const basePath = normalizeRoutePath(path);
+  const detailPath = basePath === '/' ? '/:id' : `${basePath}/:id`;
+  const deleteHandler = controller.delete ?? controller.destroy;
+
+  app.get(basePath, controller.index);
+  app.get(detailPath, controller.show);
+  app.post(basePath, controller.create);
+  app.put(detailPath, controller.update);
+
+  if (!deleteHandler) {
+    throw new TypeError(`CRUD controller for ${basePath} must define delete or destroy.`);
+  }
+
+  app.delete(detailPath, deleteHandler);
+
+  return app;
+}

package/helpers/index.ts

@@ -0,0 +1,4 @@
+export * from './route';
+export * from './config';
+export * from './crud';
+export * from '../plugins/define';

package/helpers/route.ts

@@ -0,0 +1,7 @@
+export function normalizeRoutePath(path: string) {
+  if (!path || path === '/') {
+    return '/';
+  }
+
+  return `/${path.replace(/^\/+|\/+$/g, '')}`;
+}

package/index.ts

@@ -0,0 +1,114 @@
+import { Hono } from 'hono';
+import { createHono, createApi } from './core/hono';
+import { registerCrudRoutes } from './helpers/crud';
+import type { Config } from './config';
+import type { controllers as generatedControllers } from './generated/controllers.generated';
+import type { models as generatedModels } from './generated/models.generated';
+import type { createServices as generatedCreateServices } from './generated/services.generated';
+import type * as AppModule from './core/app';
+
+type AppRuntimeModule = typeof AppModule;
+type Controllers = typeof generatedControllers;
+type Models = typeof generatedModels;
+type CreateServices = typeof generatedCreateServices;
+
+let appRuntimeModule: AppRuntimeModule | undefined;
+let controllersModule: { controllers: Controllers } | undefined;
+let modelsModule: { models: Models } | undefined;
+let servicesModule: { createServices: CreateServices } | undefined;
+let configModule: { default: Config } | undefined;
+
+function getAppRuntimeModule() {
+  appRuntimeModule ??= require('./core/app') as AppRuntimeModule;
+
+  return appRuntimeModule;
+}
+
+function getControllers() {
+  controllersModule ??= require('./generated/controllers.generated') as {
+    controllers: Controllers;
+  };
+
+  return controllersModule.controllers;
+}
+
+function getModels() {
+  modelsModule ??= require('./generated/models.generated') as { models: Models };
+
+  return modelsModule.models;
+}
+
+function getCreateServices() {
+  servicesModule ??= require('./generated/services.generated') as {
+    createServices: CreateServices;
+  };
+
+  return servicesModule.createServices;
+}
+
+function getConfig() {
+  configModule ??= require('./config') as { default: Config };
+
+  return configModule.default;
+}
+
+export { createHono, createApi, registerCrudRoutes };
+export { defineConfig, definePluginConfig } from './helpers/config';
+export { definePlugin } from './plugins/define';
+export type { AppContext, AppPlugin } from './core/app';
+export type { Config, JaxConfig } from './config';
+export { ApiController } from './core/api-controller';
+export { Controller } from './core/controller';
+export { Service } from './core/service';
+export type { ServiceContext } from './core/service';
+export type { Services } from './generated/services.generated';
+export type { ApiFailResponse, ApiResponse, ApiSuccessResponse } from './middleware/api-response';
+
+export function createApp() {
+  return getAppRuntimeModule().createApp({
+    models: getModels(),
+    createServices: getCreateServices()
+  });
+}
+
+export const controllers = new Proxy({} as Controllers, {
+  get(_target, property, receiver) {
+    return Reflect.get(getControllers(), property, receiver);
+  },
+  has(_target, property) {
+    return property in getControllers();
+  },
+  ownKeys() {
+    return Reflect.ownKeys(getControllers());
+  },
+  getOwnPropertyDescriptor(_target, property) {
+    return Object.getOwnPropertyDescriptor(getControllers(), property);
+  }
+});
+
+export const models = new Proxy({} as Models, {
+  get(_target, property, receiver) {
+    return Reflect.get(getModels(), property, receiver);
+  }
+});
+
+export const createServices: CreateServices = ((deps: unknown) => {
+  return getCreateServices()(deps);
+}) as CreateServices;
+
+export const config = new Proxy({} as Config, {
+  get(_target, property, receiver) {
+    return Reflect.get(getConfig(), property, receiver);
+  },
+  has(_target, property) {
+    return property in getConfig();
+  },
+  ownKeys() {
+    return Reflect.ownKeys(getConfig());
+  },
+  getOwnPropertyDescriptor(_target, property) {
+    return Object.getOwnPropertyDescriptor(getConfig(), property);
+  }
+});
+
+export { Hono };

package/middleware/api-response.ts

@@ -0,0 +1,44 @@
+import type { Context, MiddlewareHandler } from 'hono';
+
+export type ApiSuccessResponse<T = unknown> = {
+  code: 0;
+  msg: string;
+  data?: T;
+};
+
+export type ApiFailResponse = {
+  code: 1;
+  msg: string;
+};
+
+export type ApiResponse<T = unknown> = ApiSuccessResponse<T> | ApiFailResponse;
+
+export function ok<T>(c: Context, data?: T, msg = 'success') {
+  return c.json<ApiSuccessResponse<T>>({
+    code: 0,
+    msg,
+    data
+  });
+}
+
+export function fail(c: Context, msg: string) {
+  return c.json<ApiFailResponse>({
+    code: 1,
+    msg
+  });
+}
+
+declare module 'hono' {
+  interface Context {
+    ok: <T>(data?: T, msg?: string) => Response;
+    fail: (msg: string) => Response;
+  }
+}
+
+export const apiResponse: MiddlewareHandler = async (c, next) => {
+  // 把统一响应方法挂到 Hono Context 上，业务接口直接使用 c.ok / c.fail。
+  c.ok = <T>(data?: T, msg = 'success') => ok(c, data, msg);
+  c.fail = (msg: string) => fail(c, msg);
+
+  await next();
+};

package/middleware/jwt.ts

@@ -0,0 +1,76 @@
+import config from '../config';
+import jwt from 'jsonwebtoken';
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+type JwtAuthOptions<TPayload extends Record<string, any> = Record<string, any>> = {
+  secretSuffix: string;
+  stateKey: string;
+  validate?: (payload: TPayload, c: Context) => boolean | Promise<boolean>;
+  resolveState?: (payload: TPayload, c: Context) => unknown | Promise<unknown>;
+};
+
+function createJwtAuth<TPayload extends Record<string, any> = Record<string, any>>(
+  options: JwtAuthOptions<TPayload>
+): MiddlewareHandler {
+  return async (c, next) => {
+    const session = c.get('session');
+    const sessionData = session.get(options.stateKey);
+
+    if (sessionData) {
+      console.log('sessionData', sessionData);
+      c.state[options.stateKey] = sessionData;
+      await next();
+    }
+
+    const token = getAuthorizationToken(c);
+
+    if (!token) {
+      return c.json({ code: 401, msg: '请先登录' });
+    }
+
+    try {
+      const payload = jwt.verify(
+        token,
+        (config as any).jwt.secret + options.secretSuffix
+      ) as TPayload;
+      const valid = options.validate ? await options.validate(payload, c) : true;
+
+      if (!valid) {
+        return c.json({ code: 401, msg: '请重新登录' });
+      }
+
+      const stateValue = options.resolveState ? await options.resolveState(payload, c) : payload;
+
+      if (!stateValue) {
+        return c.json({ code: 401, msg: '请重新登录' });
+      }
+
+      c.state[options.stateKey] = stateValue;
+
+      await next();
+    } catch {
+      return c.json({ code: 401, msg: '请重新登录' });
+    }
+  };
+}
+
+function createOptionalAuth(auth: MiddlewareHandler): MiddlewareHandler {
+  return async (c, next) => {
+    if (!c.req.header('authorization')) {
+      await next();
+      return;
+    }
+
+    return auth(c, next as Next);
+  };
+}
+
+function getAuthorizationToken(c: Context) {
+  const authorization = c.req.header('authorization') ?? '';
+
+  return authorization.startsWith('Bearer ')
+    ? authorization.slice('Bearer '.length)
+    : authorization;
+}
+
+export { createJwtAuth, createOptionalAuth, getAuthorizationToken };

package/middleware/request-log.ts

@@ -0,0 +1,3 @@
+import { logger } from 'hono/logger';
+
+export const requestLog = logger();

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "jax-hono",
+  "version": "1.0.0",
+  "description": "Lightweight framework layer on top of Hono, built for Bun",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./index.ts"
+    },
+    "./*": "./*"
+  },
+  "bin": {
+    "jax": "./bin/jax.ts"
+  },
+  "files": [
+    "index.ts",
+    "setup.ts",
+    "config.ts",
+    "bin/",
+    "core/",
+    "middleware/",
+    "plugins/",
+    "helpers/",
+    "utils/",
+    "types/",
+    "build/",
+    "docs/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "echo 'jax-hono requires Bun. Visit https://bun.sh to install.'"
+  },
+  "dependencies": {
+    "@hono/session": "^0.2.1",
+    "cac": "^7.0.0",
+    "hono": "^4.12.27"
+  },
+  "peerDependencies": {
+    "dayjs": "*",
+    "deepmerge": "*",
+    "dotenv": "*",
+    "jsonwebtoken": "*",
+    "minimist": "*",
+    "mongoose": "*"
+  },
+  "peerDependenciesMeta": {
+    "dayjs": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    },
+    "jsonwebtoken": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "license": "MIT"
+}

package/plugins/config.ts

@@ -0,0 +1,8 @@
+import { definePluginConfig } from '../helpers/config';
+
+export default definePluginConfig({
+  session: {
+    enable: true,
+    package: 'jax/plugins/session'
+  }
+});

package/plugins/define.ts

@@ -0,0 +1,5 @@
+import type { AppPlugin } from '../core/app';
+
+export function definePlugin<TPlugin extends AppPlugin>(plugin: TPlugin) {
+  return plugin;
+}