Hono 是一个轻量级 TypeScript Web 框架，专为边缘计算环境设计。它支持 Cloudflare Workers、Deno、Bun、Node.js 等多种运行时，以极小的体积和出色的性能著称。
Hono 的核心特点
- 超轻量：核心包仅约 14KB，无额外依赖。
- 多运行时：同一份代码可运行在 Cloudflare Workers、Deno、Bun、Node.js 之上。
- 内置 TypeScript 支持：完整的类型推导，编辑器体验流畅。
- 丰富的中间件生态：提供认证、校验、缓存等开箱即用的中间件。
- 高性能路由：基于 Trie 树的路由匹配算法，路由注册和查找都很快。
环境准备
确保你已安装 Bun 运行时。Bun 是一个兼具 JavaScript 运行时和包管理器功能的工具。
# 检查 Bun 版本
bun --version如果没有安装，可以执行以下命令：
curl -fsSL https://bun.sh/install | bash创建项目
使用 Hono 的官方脚手架工具初始化项目：
bun create hono my-app在模板选择界面中，选择 cloudflare-workers 模板（你也可以根据需要选择其他模板）。创建完成后进入目录：
cd my-app项目的目录结构如下：
my-app/
├── src/
│ └── index.ts # 应用入口
├── package.json
├── tsconfig.json
└── wrangler.toml # Cloudflare Workers 配置第一个路由
打开 src/index.ts，你会看到类似下面的代码：
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => {
return c.text('Hello Hono!')
})
export default app这段代码做了三件事：
- 从
hono包导入Hono类。 - 创建一个
app实例。 - 注册一个 GET 路由
/，返回纯文本响应。
运行开发服务器：
bun run dev访问 http://localhost:8787，你应该能看到 Hello Hono!。
返回 JSON
API 接口通常返回 JSON 格式的数据。使用 c.json() 方法：
app.get('/api/hello', (c) => {
return c.json({
message: '你好，世界',
timestamp: Date.now(),
})
})处理请求参数
查询参数 (Query)
客户端通过 URL 问号后的参数传参：
app.get('/search', (c) => {
const q = c.req.query('q')
const page = c.req.query('page') || '1'
return c.json({ keyword: q, page: Number(page) })
})访问 /search?q=hono&page=2，返回：
{ "keyword": "hono", "page": 2 }路径参数 (Param)
路径中的动态部分用冒号声明：
app.get('/users/:id', (c) => {
const id = c.req.param('id')
return c.json({ userId: id })
})请求体 (Body)
POST 请求需要从请求体中读取数据：
app.post('/users', async (c) => {
const body = await c.req.json()
// body 类型为 unknown，需要自行校验
const name = (body as { name: string }).name
return c.json({ created: true, name }, 201)
})返回 HTML
Hono 也可以直接返回 HTML 内容：
app.get('/about', (c) => {
return c.html(`
<html>
<head><title>关于我们</title></head>
<body>
<h1>欢迎使用 Hono</h1>
<p>这是一个轻量级 Web 框架。</p>
</body>
</html>
`)
})完整的示例
下面是一个综合示例，涵盖了常见的请求处理场景：
import { Hono } from 'hono'
const app = new Hono()
// 健康检查
app.get('/health', (c) => {
return c.json({ status: 'ok', uptime: process.uptime() })
})
// 获取用户列表
app.get('/api/users', (c) => {
const page = c.req.query('page') || '1'
const limit = c.req.query('limit') || '10'
return c.json({
data: [],
page: Number(page),
limit: Number(limit),
})
})
// 创建用户
app.post('/api/users', async (c) => {
const body = await c.req.json()
return c.json({ id: Date.now(), ...body }, 201)
})
// 获取单个用户
app.get('/api/users/:id', (c) => {
const id = c.req.param('id')
// 模拟数据库查询
return c.json({ id, name: '用户 ' + id })
})
export default app小结
通过本文你已经学会了：
- Hono 的核心特点和适用场景。
- 使用
bun create hono快速初始化项目。 - 注册 GET 和 POST 路由。
- 处理查询参数、路径参数和请求体。
- 返回 JSON 和 HTML 格式的响应。
下一篇文章将介绍路由的高级用法和中间件机制。