Hello, Hono - 棒无

为什么选择 Hono.js#

Hono 起初是为 Cloudflare Workers 设计的超轻量 Web 框架，现在已支持 Deno、Bun、Node.js、Vercel Edge、Lagon 等多种运行时。它兼具以下特性：

快速：核心仅 ~15KB，响应链路短，天然适合边缘侧（Edge）与无服务器函数。
兼容 Fetch 标准：上下文就是 Request/Response，易于在不同运行时迁移。
TypeScript 友好：严格的类型推导，加上 hc/zod 等生态可自动生成客户端与 OpenAPI。
中间件生态：内置 CORS、Basic Auth、JWT、Validator 等工具，也能继承 Express 风格中间件。

本文整理 Hono 在实际项目中的最佳实践，帮助你搭建稳定、可维护的微服务 API。

项目脚手架#

推荐使用官方 CLI：

1
npm create hono@latest my-hono-app
2
cd my-hono-app
3
npm install
4
npm run dev

生成的项目默认使用 TypeScript 与 ESLint，可根据运行时切换 adapter：

cloudflare-workers
bun
deno
node-server（Node.js 运行，配合 Fastly Compute、Lambda 等）

配置建议：

在 tsconfig.json 开启 strict, noUncheckedIndexedAccess。
配置 eslint-config-hono 与 typescript-eslint 保证一致性。
使用 @hono/zod-validator 做输入校验。

路由与模块化#

Hono 按照路径注册 handler，建议按业务拆分：

1
import { Hono } from 'hono';
2
import { userRouter } from './routes/users';
3
import { authRouter } from './routes/auth';
4

5
const app = new Hono();
6

7
app.route('/auth', authRouter);
8
app.route('/users', userRouter);
9

10
export default app;

routes/users.ts：

1
import { Hono } from 'hono';
2
import { zValidator } from '@hono/zod-validator';
3
import { z } from 'zod';
4

5
export const userRouter = new Hono()
6
  .get(
7
    '/',
8
    zValidator('query', z.object({ page: z.coerce.number().int().min(1).default(1) })),
9
    async (c) => {
10
      const { page } = c.req.valid('query');
11
      const result = await c.get('services').user.list({ page });
12
      return c.json(result);
13
    }
14
  )
15
  .post(
16
    '/',
17
    zValidator('json', z.object({ email: z.string().email(), password: z.string().min(8) })),
18
    async (c) => {
19
      const payload = c.req.valid('json');
20
      const user = await c.get('services').user.create(payload);
21
      return c.json(user, 201);
22
    }
23
  );

要点：

尽量在路由文件中保持“瘦控制器”，把业务逻辑下沉到 service/domain 层。
通过 c.get()/c.set() 将服务或依赖注入 Context。
利用 zod 校验 + 类型推导避免重复声明类型。

中间件与上下文#

常用中间件示例：

1
import { logger } from 'hono/logger';
2
import { cors } from 'hono/cors';
3
import { poweredBy } from 'hono/powered-by';
4
import { secureHeaders } from 'hono/secure-headers';
5

6
app.use('*', poweredBy());
7
app.use('*', logger());
8
app.use('*', secureHeaders());
9
app.use(
10
  '/api/*',
11
  cors({
12
    origin: ['https://app.example.com'],
13
    allowMethods: ['GET', 'POST', 'PATCH', 'DELETE'],
14
    allowHeaders: ['Authorization', 'Content-Type'],
15
  })
16
);

依赖注入：

1
import type { Services } from './services';
2

3
type Bindings = {
4
  SERVICES: Services;
5
};
6

7
const app = new Hono<{ Bindings: Bindings }>();
8

9
app.use('*', async (c, next) => {
10
  c.set('services', c.env.SERVICES);
11
  await next();
12
});

执行顺序遵循注册顺序，注意在 Edge 环境中避免阻塞型操作（例如 crypto.randomUUID 可替代 uuid 包）。

错误处理#

统一错误处理能提升 DX：

1
app.onError((err, c) => {
2
  c.get('logger')?.error(err);
3

4
  if (err instanceof HTTPException) {
5
    return err.getResponse();
6
  }
7

8
  return c.json(
9
    {
10
      code: 'INTERNAL_ERROR',
11
      message: '服务器开小差了',
12
    },
13
    500
14
  );
15
});
16

17
app.notFound((c) =>
18
  c.json(
19
    {
20
      code: 'NOT_FOUND',
21
      message: `Route ${c.req.method} ${c.req.path} 不存在`,
22
    },
23
    404
24
  )
25
);

使用 HTTPException 抛出领域错误，例如 throw new HTTPException(403, { message: 'Forbidden' })。
在日志中记录 requestId（可从 header 或 crypto.randomUUID() 生成）。
Edge 平台通常有 ExecutionContext.waitUntil，可以结合 app.use 注入日志/埋点。

数据访问与性能#

Cloudflare D1、PlanetScale、Supabase 可通过 Context.env 注入客户端。
在 Edge 环境使用 fetch 调用内部服务时，注意复用 Request 对象或使用 Cache API。
结合 itty-router-openapi 或 hono-openapi 自动生成文档。
当需要 WebSocket/SSE，可引用 hono/ws 或 hono/sse。

缓存策略：

1
app.get('/health', async (c) => {
2
  return c.text('ok', 200, {
3
    'Cache-Control': 'max-age=30',
4
  });
5
});
6

7
app.get('/articles', cacheMiddleware(), async (c) => {
8
  // ...
9
});

在 Cloudflare Workers 中可用 c.executionCtx.waitUntil(cache.put(...)) 延迟写缓存。

安全最佳实践#

使用 secureHeaders() 设置 Content-Security-Policy, Strict-Transport-Security, X-Frame-Options。

JWT 验证使用 hono/jwt：

1
app.use(
2
  '/api/*',
3
  jwt({
4
    secret: c.env.JWT_SECRET,
5
    cookie: 'access_token',
6
    algorithm: 'HS256',
7
  })
8
);

对外部输入全部走 zod/valibot 校验，防止类型穿透。
对于文件上传，结合 R2/S3 签名上传 + 临时 URL。
记录审计日志：可将请求信息写入 Workers Analytics Engine 或第三方服务。

测试策略#

单元测试#

1
import { describe, it, expect } from 'vitest';
2
import app from '../src/app';
3

4
describe('GET /health', () => {
5
  it('should return ok', async () => {
6
    const res = await app.request('/health');
7
    expect(res.status).toBe(200);
8
    expect(await res.text()).toBe('ok');
9
  });
10
});

Hono 提供 app.request 直接在 Node 里模拟请求，无需启动服务器。

集成测试#

Cloudflare Workers：使用 @cloudflare/workers-types 与 miniflare。
Node 环境：搭配 supertest。
Edge Function：在部署前使用平台提供的本地模拟器（如 wrangler dev、vercel dev）。

部署与观察#

Cloudflare Workers：wrangler deploy；配置 Durable Objects、KV、R2 于 wrangler.toml。
Vercel Edge：导出 export default app，在 vercel.json 指定 runtime: "edge"。
Node Server：使用 @hono/node-server 或 fastly-hono-adapter。
Docker：将 app.fetch 包装在 server.listen 中，注意 Node 端口。

监控与日志：

Cloudflare Logs / Workers Analytics Engine。
OpenTelemetry：可结合 hono/opentelemetry 输出 trace。
使用平台原生指标（Vercel Speed Insights、Deno Deploy Metrics）。

常见陷阱#

Edge 环境没有 Node polyfills，避免依赖 fs, crypto.randomBytes 等 Node 特有 API。
await 中不要阻塞事件循环：使用 Promise.all 并行执行。
注意 Request/Response 流只能读取一次；需要复用时调用 req.clone().
app.fire() 必须在 fetch handler 中调用，在 Cloudflare 中通常是 export default app.
如果在中间件中抛异常，却返回 200，多半是 await next() 忘写。