用途:在使用 Hono 构建 API、使用 hc 客户端、实现 OpenAPI 或提到 Hono、RPC、类型安全 API 时启用。不适用于 Bun 运行时 API(用 bun-dev)及其他框架(Express、Fastify)。基于 Hono v4+ 与 @hono/zod-openapi v1.0+。
主要能力:
- 路由链式定义。类型推断沿方法链流动,写成 .get().post() 链式形式可保住类型;用变量赋值打断链式会丢失类型。路径参数自动类型化,查询参数用 @hono/zod-validator 的 zValidator 校验。
- 工厂模式。用 createFactory<Env>() 为中间件与路由提供带类型的上下文变量(如 user、requestId、db),可组装多模块路由。
- 错误处理。抛出 hono/http-exception 的 HTTPException,定义自定义错误类,用 onError 集中处理 HTTPException 与 ZodError,notFound 自定义 404;生产环境不暴露堆栈。
- Zod OpenAPI。用 createRoute、OpenAPIHono 与 .openapi() 生成规范,配合 @hono/swagger-ui 提供文档页与 /openapi.json。
- RPC 客户端。导出 export type AppType = typeof app,客户端用 hc<AppType>(baseUrl) 获得端到端类型。
- 测试。用 hono/testing 的 testClient 搭配 bun:test 编写类型安全测试。
- 中间件。logger、cors、限流、请求 ID 等,可经 factory.createMiddleware 写入类型化上下文。
使用要点:始终链式路由以保留类型推断;导出 AppType 供 RPC 使用;用 createFactory 管理上下文类型;用 Zod 校验输入;用 HTTPException 与集中 onError 处理错误;用 testClient 测试。避免打断方法链、使用 any、用 JSON.parse(await c.req.text()) 替代 c.req.json()、跳过用户输入校验、生产环境暴露堆栈。类型报错时检查链式是否被破坏、AppType 是否与实际应用一致、中间件是否经 createFactory 提供上下文、客户端是否使用正确的 param/query/json 键。
限制:具体安装命令、依赖版本之外的配置、部署平台与收费信息资料暂未提供。