hono

Hono

概述

Hono 是一个基于 Web 标准构建的小型超高速 Web 框架，可在任何 JavaScript 运行时上运行，包括 Cloudflare Workers、Bun、Deno、Node.js、Vercel 和 AWS Lambda。应用代码可在不同运行时之间移植；每个平台只需更换入口点和适配器。

适用场景： Edge 优先的 API、Cloudflare Workers 服务、多运行时应用、轻量级 REST/RPC 服务、中间件密集型请求管道、类型安全的客户端-服务端通信。

不适用场景： 全栈 SSR 框架（请使用 Next.js/Remix）、重度依赖 ORM 且需要 Express 生态成熟度的单体应用、需要使用没有 Web 标准等效方案的 Node.js 专属底层 API 的应用。

快速参考

模式	API	要点
基本路由	app.get('/path', handler)	支持 get、post、put、delete、patch、all
路径参数	app.get('/user/:id', handler)	通过 c.req.param('id') 访问
正则约束	app.get('/post/:id{[0-9]+}', handler)	在路径参数中内联正则表达式
通配符	app.get('/files/*', handler)	匹配任意子路径
路由分组	app.route('/api', subApp)	挂载子应用
中间件	app.use(middleware())	按注册顺序执行
路径中间件	app.use('/auth/*', jwt(...))	将中间件限定到指定路径
JSON 响应	c.json({ key: 'value' })	自动设置 Content-Type
文本响应	c.text('hello')	返回纯文本
HTML 响应	c.html('<h1>Hi</h1>')	返回 HTML 内容
状态码 + 标头	c.status(201)、c.header('X-Key', 'val')	在响应前链式调用
重定向	c.redirect('/new-path', 301)	默认状态码为 302
请求正文	c.req.json()、c.req.parseBody()	解析 JSON 或表单数据
查询参数	c.req.query('page')	获取单个查询参数
上下文变量	c.set('user', data) / c.get('user')	以类型安全的方式传递中间件数据
Zod 验证	zValidator('json', schema)	@hono/zod-validator 包
RPC 客户端	hc<AppType>(url)	端到端类型安全的 API 调用
错误处理器	app.onError((err, c) => ...)	全局错误处理
未找到处理器	app.notFound((c) => ...)	自定义 404 处理器
环境	c.env.BINDING_KEY	访问运行时绑定/环境变量
适配器辅助函数	来自 hono/adapter 的 env(c)	在不同运行时中统一访问环境变量
WebSocket	来自运行时适配器的 upgradeWebSocket()	支持 RPC 的 WebSocket 辅助函数
测试客户端	来自 hono/testing 的 testClient(app)	无需 HTTP 服务端即可进行类型安全的测试
JSX 流式传输	jsxRenderer({ stream: true })	支持 Suspense 的 SSR 流式传输

常见错误

错误	正确做法
在处理程序之后注册中间件	在需要应用中间件的处理程序之前注册中间件
使用 app.route() 时，RPC 类型未进行链式调用	链式调用路由方法（app.route('/a', a).route('/b', b)），并导出 typeof routes
在边缘运行时中忘记 export default app	Cloudflare Workers、Bun 和 Deno 需要默认导出
在 Cloudflare Workers 或 Deno Deploy 上使用 compress()	这些平台会自动压缩；请跳过该中间件
在 Deno 中混用 Hono 和中间件版本	将所有 hono 导入固定到同一版本，以避免类型不匹配
在中间件中将 next() 包裹在 try/catch 中	Hono 会捕获抛出的错误并将其路由到 app.onError()；next() 不会抛出错误
使用 app.get() 定义路由，却为 RPC 导出 typeof app	导出链式路由变量的类型，而非 app 实例的类型
使用 new Hono() 时未指定泛型	传入 Hono<{ Variables: MyVars }>，以启用类型化的 c.get()/c.set()
返回 c.json() 时未为已创建的资源指定状态码	将状态码作为第二个参数传入：c.json(data, 201)
未使用 createMiddleware() 创建可复用的中间件	从 hono/factory 导入，以便提取中间件时保留类型推断

委派

如果有 zod 或 typescript-patterns 技能，请将架构和类型级任务委派给它。 否则，建议使用：npx skills add oakoss/agent-skills --skill typescript-patterns

如果有 Cloudflare Workers 技能，请将平台特定配置委派给它。

参考

• 路由定义、路径参数、路由组和方法处理程序
• 内置和自定义中间件模式
• Context 对象、请求解析和响应辅助函数
• Zod 验证器中间件和请求验证
• RPC 客户端和端到端类型安全
• 适用于 Cloudflare、Bun、Node.js、Deno 等平台的运行时适配器
• 使用 testClient、WebSocket 辅助工具和 JSX 流式传输进行测试