Hono框架路由与中间件开发 hono-routing

---

name: hono-routing description: 使用路由、中间件、RPC构建类型安全的Hono API。用于请求验证、Zod/Valibot验证器，或遇到中间件类型推断、验证钩子、RPC错误。

关键词：hono, hono routing, hono middleware, hono rpc, hono validator, zod validator, valibot validator, type-safe api, hono context, hono error handling, HTTPException, c.req.valid, middleware composition, hono hooks, typed routes, hono client, middleware response not typed, hono validation failed, hono rpc type inference

license: MIT metadata: version: “2.0.0” package_version: “4.10.6” last_verified: “2025-11-21” errors_prevented: 12 templates_included: 9 references_included: 6

Hono路由与中间件

状态：生产就绪 ✅ 最后更新：2025-11-21 依赖项：无（框架无关） 最新版本：hono@4.10.6, zod@4.1.12, valibot@1.1.0

---

快速开始（5分钟）

安装

bun add hono@4.10.6  # 推荐
# 或：bun add hono@4.10.6

为什么选择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()）
• 导出应用以用于运行时

添加验证

bun add zod@4.1.12 @hono/zod-validator@0.7.4

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’) 在验证中间件后获取类型化数据

✅ 导出应用 用于部署（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个错误（参见references/top-errors.md获取所有12个）

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

问题：中间件返回响应但路由处理程序仍执行 解决方案：不要从中间件返回如果你想链继续 - 仅设置变量

// ❌ 错误 - 破坏链
app.use('*', (c) => {
  return c.json({ error: 'Unauthorized' }, 401)
})

// ✅ 正确 - 改为抛出HTTPException
app.use('*', (c, next) => {
  if (!isAuthorized) {
    throw new HTTPException(401, { message: 'Unauthorized' })
  }
  await next()
})

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

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

// ❌ 错误 - 钩子已弃用
app.post('/user', (c) => {
  const data = c.req.json<User>() // 无运行时验证！
})

// ✅ 正确 - 带运行时验证的中间件
app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json') // 已验证并类型化！
})

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

问题：中间件不调用next()，破坏链 解决方案：始终调用 await next() 除非提前返回

// ❌ 错误 - 链破坏
app.use('*', (c) => {
  console.log('Log')
  // 缺少 await next()！
})

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

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

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

// ❌ 错误 - 无类型
const app = new Hono()
c.set('user', { id: '123' }) // 未类型化
const user = c.get('user') // any

// ✅ 正确 - 类型化
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') // 完全类型化！

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

问题：客户端没有来自服务器路由的类型 解决方案：导出AppType并使用hc<AppType>

// 服务器
const routes = app.get('/users', (c) => c.json([]))
export type AppType = typeof routes // 导出这个！

// 客户端
import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('http://localhost:8787') // 完全类型化！

加载 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.string().email(),
  })),
  (c) => {
    const data = c.req.valid('json') // 类型化！
    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 vs Valibot vs ArkType vs 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 }>()

// 全局中间件
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,
}))

// 路由
app.route('/api', apiRoutes)

// 全局错误处理程序
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处理程序
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.ts - RPC客户端使用
• package.json - 依赖项配置

---

依赖项

必需：

• hono@^4.10.2 - 核心框架

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

• zod@^4.1.12 + @hono/zod-validator@^0.7.4（最流行）
• valibot@^1.1.0 + @hono/valibot-validator@^0.5.3（较小包）
• 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 vs 替代品

功能	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（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