在 Bun 上用 Hono 构建 API：路由、请求响应…

适用于在 Bun 运行时使用 Hono 框架开发 API、REST 服务或 Web 应用时，快速实现路由、请求响应、中间件、校验、错误处理和类型安全客户端。

适用场景

解决思路

1. 创建 Hono 项目：`bun create hono my-app`。
2. 进入项目目录：`cd my-app`。
3. 安装依赖：`bun install`。
4. 启动开发服务器：`bun run dev`。
5. 从 `hono` 导入 Hono：`import { Hono } from 'hono';`。
6. 创建应用实例：`const app = new Hono();`。
7. 定义根路由返回文本：`app.get('/', (c) => c.text('Hello Hono!'));`。
8. 定义 `/json` 路由返回 JSON：`app.get('/json', (c) => c.json({ message: 'Hello' }));`。
9. 导出应用：`export default app;`。
10. 注册 GET 路由：`app.get('/users', (c) => c.json([]));`。
11. 注册 POST 路由：`app.post('/users', (c) => c.json({ created: true }));`。
12. 注册 PUT 路由：`app.put('/users/:id', (c) => c.json({ updated: true }));`。
13. 注册 DELETE 路由：`app.delete('/users/:id', (c) => c.json({ deleted: true }));`。
14. 用 `app.all('/any', (c) => c.text('Any method'));` 处理所有 HTTP 方法。
15. 用路径参数读取单个参数：`app.get('/users/:id', (c) => { const id = c.req.param('id'); return c.json({ id }); });`。
16. 用 `c.req.param()` 解构读取多个路径参数：`app.get('/posts/:postId/comments/:commentId', (c) => { const { postId, commentId } = c.req.param(); return c.json({ postId, commentId }); });`。
17. 用通配符路由并通过 `c.req.path` 获取路径：`app.get('/files/*', ...)`。
18. 用类正则参数模式：`app.get('/user/:id{[0-9]+}', (c) => c.json({ id: c.req.param('id') }));`。
19. 创建路由组：`const api = new Hono();`。
20. 在路由组中注册 `api.get('/users', (c) => c.json([]));`。
21. 在路由组中注册 `api.get('/posts', (c) => c.json([]));`。
22. 挂载路由组：`app.route('/api/v1', api);`。
23. 用 basePath 创建带基础路径的应用：`const app2 = new Hono().basePath('/api/v2');`。
24. 在 basePath 应用上注册 `app2.get('/users', (c) => c.json([]));`，访问路径为 `/api/v2/users`。
25. 在 POST `/submit` 中读取请求 URL：`console.log(c.req.url);`。
26. 读取请求方法：`console.log(c.req.method);`。
27. 读取请求头：`const auth = c.req.header('Authorization');`。
28. 读取单个查询参数：`const page = c.req.query('page');`。
29. 解构读取多个查询参数：`const { limit, offset } = c.req.query();`。
30. 解析 JSON 请求体：`const json = await c.req.json();`。
31. 解析文本请求体：`const text = await c.req.text();`。
32. 解析表单请求体：`const form = await c.req.formData();`。
33. 解析 ArrayBuffer 请求体：`const arrayBuffer = await c.req.arrayBuffer();`。
34. 使用验证器后读取已解析请求体：`const body = c.req.valid('json');`。
35. 返回 `c.json({ received: true });`。
36. 返回文本响应：`c.text('Hello')`。
37. 返回 JSON 响应：`c.json({ data: 'value' })`。
38. 返回 HTML 响应：`c.html('<h1>Hello</h1>')`。
39. 返回重定向：`c.redirect('/other', 302)`。
40. 返回 Not Found：`c.notFound()`。
41. 返回自定义响应：`c.body('Raw body', 200, { 'Content-Type': 'text/plain' })`。
42. 返回带状态码的 JSON：`c.json({ error: 'Not found' }, 404)`。
43. 设置响应头：`c.header('X-Custom', 'value');`，然后 `return c.json({ ok: true });`。
44. 注册全局中间件：`app.use('*', async (c, next) => { ... });`。
45. 在全局中间件中记录请求方法和 URL：`console.log(`${c.req.method} ${c.req.url}`);`。
46. 在全局中间件中调用 `await next();` 继续执行。
47. 注册路径特定中间件：`app.use('/api/*', async (c, next) => { ... });`。
48. 在路径特定中间件中读取 `Authorization` 头：`const auth = c.req.header('Authorization');`。
49. 如果 `Authorization` 缺失，返回 `c.json({ error: 'Unauthorized' }, 401)`。
50. 如果 `Authorization` 存在，调用 `await next();`。
51. 注册多个中间件：`app.use('/admin/*', authMiddleware, adminMiddleware);`。
52. 定义受保护路由：`app.get('/api/data', (c) => c.json({ data: 'protected' }));`。
53. 从 `hono/cors` 导入 `cors`。
54. 从 `hono/logger` 导入 `logger`。
55. 从 `hono/basic-auth` 导入 `basicAuth`。
56. 从 `hono/bearer-auth` 导入 `bearerAuth`。
57. 从 `hono/compress` 导入 `compress`。
58. 从 `hono/etag` 导入 `etag`。
59. 从 `hono/secure-headers` 导入 `secureHeaders`。
60. 全局启用 CORS：`app.use('*', cors());`。
61. 为 `/api/*` 配置 CORS：`app.use('/api/*', cors({ origin: 'https://example.com', allowMethods: ['GET', 'POST'] }));`。
62. 全局启用 logger：`app.use('*', logger());`。
63. 为 `/admin/*` 启用 Basic Auth：`app.use('/admin/*', basicAuth({ username: 'admin', password: 'secret' }));`。
64. 为 `/api/*` 启用 Bearer Token：`app.use('/api/*', bearerAuth({ token: 'my-token' }));`。
65. 全局启用压缩：`app.use('*', compress());`。
66. 全局启用 ETag：`app.use('*', etag());`。
67. 全局启用安全响应头：`app.use('*', secureHeaders());`。
68. 从 `@hono/zod-validator` 导入 `zValidator`。
69. 从 `zod` 导入 `z`。
70. 定义用户校验 schema：`z.object({ name: z.string().min(1), email: z.email(), age: z.number().min(0).optional() });`。
71. 在 `POST /users` 上使用 `zValidator('json', userSchema)` 校验 JSON body。
72. 在校验后的处理器中通过 `c.req.valid('json')` 获取类型化数据并返回 `c.json({ created: user });`。
73. 定义查询参数校验 schema：`z.object({ page: z.string().regex(/^\d+$/).optional(), limit: z.string().regex(/^\d+$/).optional() });`。
74. 在 `GET /items` 上使用 `zValidator('query', querySchema)` 校验查询参数。
75. 在校验后的处理器中通过 `c.req.valid('query')` 获取 `page` 和 `limit` 并返回 JSON。
76. 定义上下文变量类型：`type Variables = { userId: string; isAdmin: boolean };`。
77. 创建带 Variables 泛型的 Hono 实例：`const app = new Hono<{ Variables: Variables }>();`。
78. 在中间件中用 `c.set('userId', '123')` 设置上下文变量。
79. 在中间件中用 `c.set('isAdmin', true)` 设置上下文变量。
80. 在处理器中用 `c.get('userId')` 读取上下文变量。
81. 在处理器中用 `c.get('isAdmin')` 读取上下文变量，并返回 JSON。
82. 从 `hono/http-exception` 导入 `HTTPException`。
83. 抛出 HTTP 错误：`throw new HTTPException(401, { message: 'Unauthorized' });`。
84. 注册全局错误处理器：`app.onError((err, c) => { ... });`。
85. 在 `onError` 中判断 `err instanceof HTTPException` 并返回 `err.getResponse()`。
86. 在 `onError` 中记录错误并返回 500 JSON：`c.json({ error: 'Internal Server Error' }, 500)`。
87. 注册 notFound 处理器：`app.notFound((c) => c.json({ error: 'Not Found' }, 404));`。
88. RPC 模式服务端：从 `hono` 导入 `Hono`，从 `hono/client` 导入 `hc`。
89. 定义链式路由：`new Hono().get('/users', (c) => c.json([{ id: 1, name: 'Alice' }])).post('/users', async (c) => { const body = await c.req.json(); return c.json({ created: body }); });`。
90. 导出类型：`export type AppType = typeof app;`。
91. 客户端从 `hono/client` 导入 `hc`。
92. 客户端从 `./server` 导入类型 `AppType`。
93. 创建类型安全客户端：`const client = hc<AppType>('http://localhost:3000');`。
94. 调用 `client.users.$get()` 发起类型安全 GET 请求。
95. 用 `await res.json()` 获取类型化用户数据。
96. 调用 `client.users.$post({ json: { name: 'Bob' } })` 发起类型安全 POST 请求。
97. 排查 `Route not found`：错误原因是路径错误，修复是检查路由注册。
98. 排查 `Body already read`：错误原因是重复解析，修复是只读取一次 body。
99. 排查 `Validator error`：错误原因是输入无效，修复是检查 schema 定义。
100. 排查 `Middleware order`：错误原因是执行顺序错误，修复是先注册中间件。
101. 需要完整中间件参考或自定义中间件模式时，加载 `references/middleware-list.md`。
102. 需要 OpenAPI/Swagger 集成或 API 文档生成时，加载 `references/openapi.md`。

适用边界 · 注意事项

• 不使用 Bun 或 Hono，而使用 Node.js/Express、Deno/Fresh 等其他运行时或框架时不适用。
• 不需要类型安全 RPC 或 Zod 校验时，不必强行引入相关依赖与模式。
• 无法使用或不想引入 Bun 作为运行时/包管理器时不适用。