Hono

是什么，为什么存在

Hono 是一个 TypeScript Web 框架。它把路由、请求读取、响应构造和中间件建立在 Web 标准 API 上，处理器接收上下文并最终返回 Response。同一应用核心可以配合 Cloudflare Workers、Node.js、Deno、Bun 等运行时的入口或适配器。

它解决的主要问题不是“怎样监听一个端口”，而是怎样用一致的 HTTP 编程模型描述应用。 传统 Node.js 框架常把处理器绑在特定服务器对象和请求对象上；Hono 则让路由核心面对 Request 与 Response，部署层负责把运行时事件接到这个核心。

处理器收到的 Hono 上下文（Hono Context） 通常命名为 c。 c.req 提供路径参数、查询参数、请求头和已验证数据等便捷接口，c.req.raw 保留原始 Request。c.json()、c.text() 和 c.body() 等方法用于构造响应。

Hono 的 中间件（middleware） 是一组围绕后续处理步骤执行的函数。 中间件可以在 await next() 前检查请求，也可以在其后修改响应头或记录结果。 路由与中间件的注册顺序属于程序行为，不是单纯的代码排版。

Hono 适合 HTTP API、边缘函数、小型服务和需要共享 TypeScript 路由类型的同仓库应用。 如果业务依赖大量 Node.js 专用库，或者团队需要完整的依赖注入、任务队列和 ORM 约定， 选择时仍要评估运行时能力与生态，而不能仅凭框架核心采用 Web 标准就推断整个应用可移植。

边缘运行时（edge runtime） 通常限制进程生命周期、文件系统、 套接字或 Node.js 内置模块。Hono 能减少 HTTP 层的运行时差异，但数据库驱动、环境变量、 后台任务和持久状态仍由具体平台决定。

Hono 还提供 Hono RPC ，让 hc 客户端从服务端应用类型推导路径、 参数和响应类型。这里的 RPC 是类型化 HTTP 客户端模式，不会绕过 HTTP，也不会把 TypeScript 的静态检查变成线上请求的运行时验证。

本主题只讲 Hono 的 HTTP 核心。JSX、流式渲染、WebSocket、OpenAPI、Cloudflare D1 与 R2 都有独立的部署或产品约束，把它们塞进一个入门应用会掩盖真正需要掌握的路由边界。

工作原理

创建 new Hono() 后，应用会按调用顺序登记路由和中间件。请求进入时，路由器根据 HTTP 方法与路径选择匹配链，再创建上下文并执行链中的函数。处理器返回的值必须能形成 一个 Response；没有返回响应的分支会在运行时失败。

一次典型请求可以画成下面的执行流。箭头返回部分很重要，因为响应阶段的日志、计时和 响应头设置通常位于 await next() 之后。

中间件通过 await next() 把控制权交给链中下一项。下一项完成后，控制权按相反方向返回。 中间件若直接返回响应而不调用 next()，后面的验证、授权或处理器不会执行；这正是认证拒绝 和缓存命中的常用短路方式。

路由可以读取 c.req.param()、c.req.query()、c.req.header() 和请求体。 这些值来自不可信 HTTP 输入，即使 TypeScript 把变量标成 string，也只说明框架读取后的 静态表示。格式、范围、允许值与字段组合仍要在运行时验证。

内置 validator() 中间件把某个输入目标交给验证函数。验证成功时，处理器通过 c.req.valid(target) 读取清洗后的值；验证函数返回 Response 时，请求会在进入业务处理器前 结束。第三方验证器可以提供更丰富的模式，但信任边界相同。

app.onError() 处理链中抛出的错误，app.notFound() 处理没有路由匹配的请求。预期的业务分支 通常应直接返回明确状态与稳定错误结构；异常处理器适合真正的异常路径，并且不应把内部错误 消息原样暴露给客户端。

app.request() 接受路径或 Request，让测试直接经过路由、中间件与响应构造而无需监听端口。 它适合验证状态码、响应头和正文。平台绑定可以作为环境参数传入测试，但真实适配器、平台权限 和外部服务仍需要更高层的集成测试。

Hono RPC 的类型来自链式路由声明的最终类型。type AppType = typeof route 保留已登记的路径， hc<AppType>() 再生成客户端形状。服务端与客户端使用不兼容的类型或版本时，编译通过并不能 证明部署中的服务正实现同一份契约。

示例

下面四个示例逐步加入路由输入、中间件、运行时验证和类型化客户端。它们在 Hono 4.13.5、Node 24.14.0 和 TypeScript 6.0.3 下编译，并由 npx tsx 实际执行。

路径参数与查询参数

第一个应用登记一条 GET 路由。app.request() 构造的请求走过真实路由器，处理器分别读取 路径参数与可选查询参数，再返回 JSON 响应。

c.req.param('id') 返回已经匹配的路径片段，查询参数则不属于路径匹配本身。 这里把唯一允许值 lines 映射为布尔量，所以其他字符串得到 false。若公开契约需要拒绝 未知查询值，应显式验证并返回 400，不能静默把所有输入当成同一个值。

中间件顺序与短路

第二个应用先登记覆盖 /api/* 的外层中间件，再登记更窄的认证中间件。未授权请求被短路， 授权请求才到达处理器；两条路径都会返回外层中间件并设置请求标识响应头。

import { Hono } from 'hono'

const app = new Hono()
const events: string[] = []

app.use('/api/*', async (c, next) => {
  events.push('request:start')
  await next()
  c.header('x-request-id', 'req-7')
  events.push('request:end')
})

app.use('/api/private/*', async (c, next) => {
  events.push('auth:check')
  if (c.req.header('authorization') !== 'Bearer demo') {
    return c.json({ error: 'Unauthorized' }, 401)
  }
  await next()
})

app.get('/api/private/profile', (c) => {
  events.push('handler')
  return c.json({ user: 'Ada' })
})

async function call(headers?: Record<string, string>) {
  events.length = 0
  const response = await app.request('/api/private/profile', { headers })
  console.log(response.status, response.headers.get('x-request-id'))
  console.log(events.join(' > '))
}

async function main() {
  await call()
  await call({ authorization: 'Bearer demo' })
}

main()

401 req-7
request:start > auth:check > request:end
200 req-7
request:start > auth:check > handler > request:end

输出展示了洋葱式回程，而不是简单的从上到下列表。认证失败时没有 handler 事件，说明 返回 401 已经终止后续链。真实认证还必须验证凭据、主体与授权范围，示例中的固定令牌只用于 展示控制流。

在运行时验证 JSON

第三个应用使用内置 validator() 检查 JSON 请求体。验证器返回清洗后的订单后，处理器从 c.req.valid('json') 读取它；无效数量则在业务处理器之前得到 400。

import { Hono } from 'hono'
import { validator } from 'hono/validator'

type OrderInput = { sku: string; quantity: number }

const app = new Hono()

app.post('/orders', validator('json', (value, c) => {
  const input = value as Partial<OrderInput>
  if (typeof input.sku !== 'string' || input.sku.trim() === '' ||
      !Number.isInteger(input.quantity) || input.quantity! < 1) {
    return c.json({ error: 'Invalid order' }, 400)
  }
  return { sku: input.sku.trim(), quantity: input.quantity! }
}), (c) => {
  const order = c.req.valid('json')
  return c.json({ id: 'ord-7', ...order }, 201)
})

async function main() {
  for (const body of [
    { sku: 'tea-1', quantity: 2 },
    { sku: 'tea-1', quantity: 0 },
  ]) {
    const response = await app.request('/orders', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(body),
    })
    console.log(response.status, await response.text())
  }
}

main()

201 {"id":"ord-7","sku":"tea-1","quantity":2}
400 {"error":"Invalid order"}

as Partial<OrderInput> 只帮助验证函数实现检查，不会验证网络数据。真正的边界是后续的 类型判断与整数范围判断。JSON 验证还依赖正确的 Content-Type；客户端媒体类型错误时， 应用应按自己的 HTTP 契约测试并返回一致响应。

从路由类型创建客户端

最后一个示例把链式路由的类型交给 hc。为了让示例保持自包含，自定义 fetch 把客户端 产生的请求直接送入应用；生产客户端通常使用全局 fetch 访问已部署地址。

import { Hono } from 'hono'
import { hc } from 'hono/client'

const route = new Hono().get('/users/:id', (c) => {
  return c.json({
    id: c.req.param('id'),
    name: 'Ada',
  })
})

type AppType = typeof route

const client = hc<AppType>('http://local', {
  fetch: (input: RequestInfo | URL, init?: RequestInit) =>
    route.fetch(new Request(input, init)),
})

async function main() {
  const response = await client.users[':id'].$get({
    param: { id: 'u-7' },
  })

  console.log(response.status, await response.text())
}

main()

200 {"id":"u-7","name":"Ada"}

客户端能检查路径参数名称，并根据服务端返回值推导响应。它不会验证实际部署版本，也不会 替代超时、认证、错误分支和响应正文的运行时测试。服务端类型应从受控包发布，不能让浏览器 客户端导入包含服务器密钥或带副作用入口的实现模块。

陷阱

把 TypeScript 类型当成输入验证

修复方法： 在路由边界执行运行时验证，使用 c.req.valid() 中的清洗结果，并分别测试 错误媒体类型、畸形 JSON、缺字段、边界值与未知字段策略。

把中间件写在受保护路由之后

修复方法： 把跨路由策略放在受影响路由之前，并用未授权请求逐条测试保护范围。 对于调用 next() 的中间件，检查进入阶段与返回阶段都执行；对于短路分支，明确返回 Response。

假设 Web 标准等于完整可移植性

修复方法： 把平台绑定放进明确的 Bindings 类型和适配层。针对每个目标运行时检查依赖， 并在部署环境执行冒烟测试；不要在 Cloudflare 示例中偷偷依赖 process.env 或 Node.js 文件系统。

把进程内状态当成持久状态

修复方法： 把业务事实放到支持所需事务与一致性的外部存储。缓存必须允许丢失并有失效策略； 限流与幂等键需要能够在实际部署拓扑中原子协调的后端。

把 Hono RPC 当成线上契约证明

修复方法： 固定兼容的 Hono 版本，发布可追踪的服务端类型制品，并保留针对真实 HTTP 边界的契约测试。公开 API 还需要独立的版本与兼容策略。

延伸阅读

• Hono 文档
• Hono 路由
• Hono 中间件指南
• Hono 验证指南
• Hono RPC 指南
• Hono 测试指南