hono-routing

Hono 路由与中间件

状态：已可用于生产环境 ✅ 上次更新：2025-11-21 依赖项：无（与框架无关） 最新版本：[email protected], [email protected], [email protected]

---

快速入门（5 分钟）

安装

bun add [email protected]  # preferred
# or: bun add [email protected]

为什么选择 Hono：

• 快速：基于 Web 标准构建，可在任何 JavaScript 运行时上运行
• 轻量：约 10KB，无依赖项
• 类型安全：完整支持 TypeScript，并具备类型推断
• 灵活：可在 Cloudflare Workers、Deno、Bun、Node.js、Vercel 上运行

基础应用

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  return c.json({ message: 'Hello Hono!' })
})

export default app

重要：

• 使用 c.json()、c.text()、c.html() 返回响应
• 返回响应（不要像 Express 那样使用 res.send()）
• 为运行时导出 app

添加验证

bun add [email protected] @hono/[email protected]

import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const schema = z.object({
  name: z.string(),
  age: z.number(),
})

app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json({ success: true, data })
})

---

关键规则

始终执行

✅ 从处理程序返回响应（c.json、c.text、c.html 等）

✅ 验证中间件之后使用 c.req.valid('source') 获取带类型的数据

✅ 为部署导出 app（Cloudflare Workers、Bun、Deno、Node.js）

✅ 使用验证中间件（zValidator、vValidator）获取类型安全的请求数据

✅ 在中间件中调用 await next()，将控制权传递给下一个处理程序

✅ 对预期错误使用 HTTPException（返回正确的 HTTP 状态码）

✅ 使用模板标签验证器（zValidator、vValidator），而不是钩子

✅ 为自定义变量定义上下文类型（Hono<{ Variables: { ... } }>）

✅ 使用子应用（app.route()）组织大型 API

✅ 为 RPC 路由添加类型（export type AppType = typeof routes），供客户端使用

绝不执行

❌ 绝不忘记从处理程序返回响应

❌ 未经验证，绝不直接使用 req.json()——使用 c.req.valid()

❌ 绝不将验证钩子与中间件混用——只使用中间件

❌ 绝不忘记在中间件中调用 await next()——这会中断中间件链

❌ 绝不使用 res.send()——此方法不可用（使用 c.json()、c.text() 等）

❌ 绝不跳过错误处理——使用 app.onError() 设置全局处理程序

❌ 验证中间件之后绝不访问未经验证的数据

❌ 绝不在中间件中使用阻塞操作——这会中断异步链

❌ 绝不在 CORS 中硬编码来源——使用环境变量

❌ 绝不跳过 RPC 类型导出——客户端将无法获得类型

---

最常见的 5 个错误（全部 12 个错误请参阅 references/top-errors.md）

错误 #1：中间件响应未进行类型化

问题：中间件返回响应，但路由处理程序仍会执行 解决方案：如果希望调用链继续执行，不要从中间件返回——只设置变量

// ❌ Wrong - breaks chain
app.use('*', (c) => {
  return c.json({ error: 'Unauthorized' }, 401)
})

// ✅ Correct - throw HTTPException instead
app.use('*', (c, next) => {
  if (!isAuthorized) {
    throw new HTTPException(401, { message: 'Unauthorized' })
  }
  await next()
})

错误 #2：混淆验证钩子与中间件

问题：使用验证钩子而不是中间件 解决方案：始终使用中间件验证器（zValidator、vValidator）

// ❌ Wrong - hooks deprecated
app.post('/user', (c) => {
  const data = c.req.json<User>() // No runtime validation!
})

// ✅ Correct - middleware with runtime validation
app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json') // Validated & typed!
})

错误 #3：中间件中缺少 await next()

问题：中间件未调用 next()，导致调用链中断 解决方案：除非提前返回，否则始终调用 await next()

// ❌ Wrong - chain broken
app.use('*', (c) => {
  console.log('Log')
  // Missing await next()!
})

// ✅ Correct
app.use('*', async (c, next) => {
  console.log('Log')
  await next()
})

错误 #4：上下文变量类型推断

问题：c.get() 和 c.set() 未进行类型化 解决方案：在 Hono 构造函数中定义 Variables 类型

// ❌ Wrong - no types
const app = new Hono()
c.set('user', { id: '123' }) // Not typed
const user = c.get('user') // any

// ✅ Correct - typed
type Variables = {
  user: { id: string; name: string }
}
const app = new Hono<{ Variables: Variables }>()
c.set('user', { id: '123', name: 'Alice' })
const user = c.get('user') // Fully typed!

错误 #5：RPC 类型推断不起作用

问题：客户端无法获取服务器路由的类型 解决方案：导出 AppType 并使用 hc

// Server
const routes = app.get('/users', (c) => c.json([]))
export type AppType = typeof routes // Export this!

// Client
import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('http://localhost:8787') // Fully typed!

加载 references/top-errors.md，查看全部 12 个错误及其详细解决方案。

---

常见用例

用例 1：基础 REST API

适用场景：简单的 CRUD 操作 快速模式：

app.get('/users', (c) => c.json({ users: [] }))
app.post('/users', (c) => c.json({ created: true }))
app.get('/users/:id', (c) => c.json({ user: {} }))
app.put('/users/:id', (c) => c.json({ updated: true }))
app.delete('/users/:id', (c) => c.json({ deleted: true }))

加载：references/setup-guide.md → 完整示例

用例 2：请求验证（Zod）

适用场景：需要类型安全的请求验证 快速模式：

import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

app.post('/user',
  zValidator('json', z.object({
    name: z.string(),
    email: z.email(),
  })),
  (c) => {
    const data = c.req.valid('json') // Typed!
    return c.json(data)
  }
)

加载：references/validation-libraries.md

用例 3：类型安全的 RPC

适用场景：共享类型的全栈 TypeScript 加载：references/rpc-guide.md + templates/rpc-pattern.ts

用例 4：中间件组合

适用场景：身份验证、日志记录、速率限制 加载：references/middleware-catalog.md + templates/middleware-composition.ts

用例 5：自定义上下文变量

何时使用：在中间件和路由之间共享数据 加载：templates/context-extension.ts

---

何时加载参考资料

在以下情况下加载 references/setup-guide.md：

• 用户需要完整的设置指南
• 用户询问如何部署到不同的运行时
• 用户需要 CRUD API 示例
• 用户想尝试其他验证器（Valibot、ArkType、Typia）

在以下情况下加载 references/top-errors.md：

• 遇到 12 种已记录错误中的任何一种
• 用户遇到中间件类型问题
• 用户不清楚验证钩子与中间件的区别
• 用户需要故障排查或调试

在以下情况下加载 references/common-patterns.md：

• 用户询问代码示例或最佳实践
• 用户需要路由分组、错误处理、文件上传模式
• 用户想要流式处理、WebSocket 或分页示例

在以下情况下加载 references/middleware-catalog.md：

• 用户需要内置中间件（cors、logger、jwt、cache、compress、etag）
• 用户想要创建自定义中间件
• 用户询问身份验证或授权

在以下情况下加载 references/rpc-guide.md：

• 用户正在构建全栈 TypeScript 应用
• 用户想要类型安全的客户端/服务端通信
• 用户询问 hono/client 或 RPC 模式

在以下情况下加载 references/validation-libraries.md：

• 用户正在比较 Zod、Valibot、ArkType 和 Typia
• 用户需要各个库的验证示例
• 用户询问性能或包体积

---

配置参考

最小配置

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.json({ message: 'Hello' }))

export default app

生产环境配置

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { HTTPException } from 'hono/http-exception'

type Variables = {
  user: { id: string; name: string }
  requestId: string
}

const app = new Hono<{ Variables: Variables }>()

// Global middleware
app.use('*', logger())
app.use('*', async (c, next) => {
  c.set('requestId', crypto.randomUUID())
  await next()
})

app.use('*', cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
  credentials: true,
}))

// Routes
app.route('/api', apiRoutes)

// Global error handler
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json(
      { error: err.message },
      err.status
    )
  }

  console.error(err)
  return c.json(
    { error: 'Internal Server Error' },
    500
  )
})

// 404 handler
app.notFound((c) => {
  return c.json({ error: 'Not Found' }, 404)
})

export default app

---

使用捆绑资源

参考资料（references/）

• setup-guide.md - 完整的 6 步设置指南（安装 → 部署）
• top-errors.md - 全部 12 种错误及其解决方案
• common-patterns.md - 7 种生产环境模式（RPC、中间件、错误处理、文件上传）
• middleware-catalog.md - 内置中间件参考（cors、logger、jwt、cache）
• rpc-guide.md - 类型安全的 RPC 客户端/服务端指南
• validation-libraries.md - Zod、Valibot、ArkType、Typia 对比

模板（templates/）

• routing-patterns.ts - 路由示例（参数、查询、通配符、分组）
• validation-zod.ts - Zod 验证示例
• validation-valibot.ts - Valibot 验证示例
• middleware-composition.ts - 身份验证、速率限制、日志记录中间件
• error-handling.ts - HTTPException 和全局错误处理器
• context-extension.ts - 自定义上下文变量
• rpc-pattern.ts - RPC 服务端设置
• rpc-client.tsx - RPC 客户端用法
• package.json - 依赖配置

---

依赖项

必需：

• hono@^4.12.12 - 核心框架

选择一个验证器（推荐）：

• zod@^4.3.6 + @hono/zod-validator@^0.7.4（最受欢迎）
• valibot@^1.1.0 + @hono/valibot-validator@^0.6.1（包体积更小）
• arktype@^2.0.0 + @hono/arktype-validator@^0.1.0（运行时速度最快）
• typia@^7.0.0 + @hono/typia-validator@^0.1.0（编译时验证）

可选：

• @hono/node-server - Node.js 适配器
• @cloudflare/workers-types - Workers 的 TypeScript 类型

---

官方文档

• Hono：https://hono.dev
• GitHub：https://github.com/honojs/hono (17.8k ⭐)
• API 参考：https://hono.dev/docs/api/hono
• 路由：https://hono.dev/docs/api/routing
• 中间件：https://hono.dev/docs/guides/middleware
• 验证：https://hono.dev/docs/guides/validation
• RPC：https://hono.dev/docs/guides/rpc
• 示例：https://github.com/honojs/hono/tree/main/examples

---

对比：Hono 与替代方案

特性	Hono	Express	Fastify
大小	~10KB	~200KB	~100KB
TypeScript	✅ 原生支持	⚠️ 类型支持	✅ 原生支持
类型推断	✅ 完整	❌ 不支持	⚠️ 有限
RPC	✅ 内置	❌ 不支持	❌ 不支持
边缘运行时	✅ 支持	❌ 不支持	❌ 不支持
验证	✅ 插件	⚠️ 手动	✅ 插件
速度	非常快	快	非常快

建议：

• 适合使用 Hono 的情况：使用 TypeScript、边缘运行时、完整类型推断、小型打包体积
• 适合使用 Express 的情况：旧版 Node.js 应用、需要庞大的生态系统
• 适合使用 Fastify 的情况：仅使用 Node.js、需要速度最快的 Node.js 框架

---

生产环境示例

已验证可运行的项目：

1. Cloudflare Workers API：https://github.com/honojs/examples/tree/main/cloudflare-workers
2. Bun REST API：https://github.com/honojs/examples/tree/main/bun
3. Deno API：https://github.com/honojs/examples/tree/main/deno
4. Node.js API：https://github.com/honojs/examples/tree/main/nodejs

---

安全安装

安装 Hono 和中间件包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审核新版本的包
• 安装前审计 — 运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查包

加载 dependency-upgrade skill，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

完整设置清单

• 已安装 Hono（bun add hono）
• 已安装验证器（Zod、Valibot、ArkType 或 Typia）
• 已创建带路由的基础应用
• 已为路由添加验证中间件
• 已为跨源请求配置 CORS
• 已添加全局错误处理器（app.onError）
• 已添加 404 处理器（app.notFound）
• 已为自定义变量配置上下文类型
• 已在本地测试路由
• 已部署到目标运行时（Cloudflare、Bun、Deno、Node.js）

---

有问题？遇到故障？

1. 查看 references/top-errors.md，了解全部 12 个错误及其解决方案
2. 查看 references/setup-guide.md，了解完整的设置流程
3. 查看 references/common-patterns.md，了解生产环境模式
4. 查看 references/middleware-catalog.md，了解内置中间件
5. 查看 references/rpc-guide.md，了解类型安全的客户端/服务端
6. 查看官方文档：https://hono.dev