@n2js/hono-module

简体中文 | English

@n2js/hono-module 是面向 Hono 的模块化路由适配包。它适合想把 Hono routes 拆成独立模块，同时完整保留 route tuple、RPC client 和 handler 上下文类型推断的项目。defineHonoModule() 会把多段 Hono 路由合并成只读 router artifact，并挂到 @n2js/container 的模块实例上，让 Hono 模块化路由、依赖解析和类型推断一起工作。

当前包提供 ESM-only 构建产物，运行入口为 ./dist/index.js，类型声明入口为 ./dist/index.d.ts。

为什么适合 Hono 模块化

• 保留路由类型推断： 合并 route tuple 后仍保留 Hono RPC 类型，不把 router 降级成宽泛的运行时对象。
• 按模块组织路由： 每个模块可以拥有自己的 routes、Provider、imports、features 和 lifecycle。
• handler 内可解析依赖： context.var.module 指向当前模块实例，业务路由可以直接解析本模块可见的 Provider。
• 子模块自动组合： 使用 mount() 组合子模块时，会按 mount path 合并子模块 router。
• 搜索友好定位： 如果你在找 Hono module、Hono modular routing 或 Hono route type inference，这个包就是为这类场景准备的。

安装

npm install @n2js/hono-module @n2js/container hono

@n2js/container 和 hono 是 peer dependencies。请在使用侧安装它们，并尽量保持单实例，避免模块 token 与 router 类型来自不同依赖副本。

快速开始

import { Container } from '@n2js/container';
import { Hono } from 'hono';
import { defineHonoModule, type THonoModuleEnv } from '@n2js/hono-module';

class GreetingService {
  getMessage(): string {
    return 'Hello from DI';
  }
}

const greetingRouter = new Hono<THonoModuleEnv>().get('/greeting', async (context) => {
  const greetingService = await context.var.module.resolve(GreetingService);

  return context.text(greetingService?.getMessage() ?? 'missing');
});

const HonoExampleModule = defineHonoModule({
  displayName: 'HonoExampleModule',
  routes: [greetingRouter] as const,
  providers: [GreetingService],
});

const container = new Container(HonoExampleModule);
const response = await container.root.router.request('/greeting');

console.log(await response.text());

核心能力

• defineHonoModule()：定义带 Hono router artifact 的模块，并保留 route tuple 类型推断。
• mergeHonoRoutes()：合并 route tuple、base path 和 mounted child routers。
• THonoModuleEnv：为 Hono Context 增加 context.var.module 类型。
• TMergedHonoRouter：保留 route tuple 推导出的 Hono RPC 类型。
• mount() 子模块时，会按 mount path 自动组合子模块 router。

使用说明

defineHonoModule() 接收与 defineModule() 相同的 Provider、imports、features 和 lifecycle 选项，同时增加 routes 与 basePath。返回的模块可以直接传给 new Container()，并通过 container.root.router 处理请求。

业务路由中的 context.var.module 是当前模块实例。你可以在 handler 中调用 resolve()、resolveOwn() 或 resolveWithScope()，也可以读取模块 Feature 附加的只读 artifact。

类型导出

| 导出 | 说明 | | --- | --- | | defineHonoModule() | 定义 Hono 模块并生成合并后的 router。 | | mergeHonoRoutes() | 独立合并 Hono route tuple。 | | THonoModuleEnv | Hono env 类型，包含当前模块实例。 | | THonoModuleOptions | defineHonoModule() 的选项类型。 | | TMergedHonoRouter | 合并后 router 的类型工具。 |

许可证

MIT