hono

Hono

API リファレンス全般、組み込みミドルウェアすべて、ランタイムのセットアップ例については、Context7 MCP（resolve-library-id の後に query-docs）を使用してください。

概要

API やサーバーサイドアプリケーション向けの、軽量で高速な Web フレームワークです。Hono 4.x は、一貫した API で Node.js、Bun、Deno、Cloudflare Workers に対応しています。

インストール: pnpm add hono

ワークフロー

基本的な API の作成:

1. Hono アプリのインスタンスを作成します: const app = new Hono()
2. HTTP メソッドでルートを定義します
3. ミドルウェアを追加します（CORS、ロガー、エラー処理）
4. ランタイムアダプター向けにアプリをエクスポートします
5. curl または Postman でエンドポイントをテストします

バリデーションの追加:

1. Zod をインストールします: pnpm add zod @hono/zod-validator
2. Zod でスキーマを定義します
3. ルートに zValidator ミドルウェアを適用します
4. バリデーションエラーを処理します
5. c.req.valid() で型安全なリクエストデータにアクセスします

ランタイムのセットアップ

// Node.js
import { Hono } from 'hono';
import { serve } from '@hono/node-server';
const app = new Hono();
serve({ fetch: app.fetch, port: 3000 });

// Bun
export default { port: 3000, fetch: app.fetch };

// Cloudflare Workers
export default app;

ルーティング

// HTTP methods
app.get('/users', (c) => c.json({ users: [] }));
app.post('/users', (c) => c.json({ created: true }, 201));
app.put('/users/:id', (c) => c.json({ updated: true }));
app.delete('/users/:id', (c) => c.json({ deleted: true }));
app.on(['GET', 'POST'], '/multi', (c) => c.text(c.req.method));

// Path parameters
app.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ userId: id });
});

// Multiple params
app.get('/posts/:postId/comments/:commentId', (c) => {
  const { postId, commentId } = c.req.param();
  return c.json({ postId, commentId });
});

// Wildcard
app.get('/files/*', (c) => c.text('File handler'));

// Regex constraint (only numeric IDs)
app.get('/posts/:id{[0-9]+}', (c) => c.json({ id: c.req.param('id') }));

ルートグループ

const v1 = new Hono();
v1.get('/users', (c) => c.json({ version: 1, users: [] }));

const v2 = new Hono();
v2.get('/users', (c) => c.json({ version: 2, users: [] }));

app.route('/api/v1', v1);
app.route('/api/v2', v2);

リクエストの処理

// Query params
app.get('/search', (c) => {
  const q = c.req.query('q');
  const page = c.req.query('page') ?? '1';
  return c.json({ q, page });
});

// JSON body
app.post('/users', async (c) => {
  const body = await c.req.json();
  return c.json({ received: body });
});

// Headers
app.get('/me', (c) => {
  const auth = c.req.header('Authorization');
  c.header('X-Custom-Header', 'value');
  return c.json({ auth });
});

レスポンスの種類

c.json({ data: 'value' })          // JSON (default 200)
c.json({ created: true }, 201)     // JSON with status
c.text('OK')                       // Plain text
c.html('<h1>Hello</h1>')           // HTML
c.redirect('/new')                 // 302 redirect
c.redirect('https://example.com', 301)
c.notFound()                       // 404

ミドルウェア

import { logger } from 'hono/logger';
import { cors } from 'hono/cors';
import { secureHeaders } from 'hono/secure-headers';
import { prettyJSON } from 'hono/pretty-json';

app.use('*', logger());
app.use('*', secureHeaders());
app.use('*', cors({
  origin: ['http://localhost:3000', 'https://example.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
}));
if (process.env.NODE_ENV === 'development') {
  app.use('*', prettyJSON());
}

カスタムミドルウェア

// Auth middleware — store data in context
const authMiddleware = async (c, next) => {
  const token = c.req.header('Authorization');
  if (!token) return c.json({ error: 'Unauthorized' }, 401);
  c.set('user', { id: 1, name: 'Alice' }); // stored in context
  await next();
};

app.use('/api/*', authMiddleware);

app.get('/api/profile', (c) => {
  const user = c.get('user');
  return c.json({ user });
});

Zod によるバリデーション

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

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(120).optional(),
});

// Validate body
app.post('/users', zValidator('json', userSchema), async (c) => {
  const user = c.req.valid('json'); // fully typed
  return c.json({ created: true, user }, 201);
});

// Validate path params
app.get('/users/:id', zValidator('param', z.object({ id: z.string().regex(/^\d+$/) })), (c) => {
  const { id } = c.req.valid('param');
  return c.json({ userId: id });
});

// Custom validation error response
app.post('/users', zValidator('json', userSchema, (result, c) => {
  if (!result.success) {
    return c.json({ error: 'Validation failed', details: result.error.flatten() }, 400);
  }
}), handler);

エラー処理

import { HTTPException } from 'hono/http-exception';

// Global error handler
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json({ error: err.message, status: err.status }, err.status);
  }
  return c.json({
    error: 'Internal Server Error',
    message: process.env.NODE_ENV === 'development' ? err.message : undefined,
  }, 500);
});

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

// Throw HTTP exceptions from route handlers
app.get('/protected', (c) => {
  throw new HTTPException(403, { message: 'Forbidden' });
});

型安全性

型付きコンテキスト変数

type Env = {
  Variables: { user: { id: number; name: string } };
};

const app = new Hono<Env>();

app.use('/api/*', async (c, next) => {
  c.set('user', { id: 1, name: 'Alice' }); // type-checked
  await next();
});

app.get('/api/profile', (c) => {
  const user = c.get('user'); // fully typed
  return c.json({ user });
});

RPC の型安全性（Hono クライアント）

// server.ts — export the app type
const app = new Hono()
  .get('/posts', (c) => c.json({ posts: [] }))
  .post('/posts', async (c) => c.json({ created: true }, 201));

export type AppType = typeof app;

// client.ts — fully typed calls, no separate OpenAPI spec needed
import { hc } from 'hono/client';
import type { AppType } from './server';

const client = hc<AppType>('http://localhost:3000');
const res = await client.posts.$get();
const data = await res.json(); // { posts: [] }

テスト

import { describe, it, expect } from 'vitest';

describe('API', () => {
  const app = new Hono();
  app.get('/hello', (c) => c.json({ message: 'Hello' }));

  it('returns hello', async () => {
    const res = await app.request('/hello');
    expect(res.status).toBe(200);
    expect(await res.json()).toEqual({ message: 'Hello' });
  });

  it('handles POST', async () => {
    app.post('/users', async (c) => {
      const body = await c.req.json();
      return c.json({ created: true, user: body }, 201);
    });

    const res = await app.request('/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: 'Alice' }),
    });

    expect(res.status).toBe(201);
  });
});

ベストプラクティス

• ルートグループを使用して関連するエンドポイントをモジュール化されたルーターに整理します
• すべての入力を Zod で検証して型安全性と実行時バリデーションを確保します
• ミドルウェアは必要なものだけを適用します — ルートグループごとに必要なものだけを使用します
• 本番環境では明示的な CORS ポリシーを設定します — 本番環境で許容範囲の広い CORS を使用しないでください
• ミドルウェアで設定する変数には、型付きコンテキスト（Hono<Env>）を使用します
• 一貫したエラーレスポンスのため、app.onError() でエラーをグローバルに処理します
• エラーレスポンスを手動で構築する代わりに、HTTPException を使用します
• app.request() でテストします — Hono 組み込みのテストユーティリティです（サーバーは不要です）
• 型安全なクライアントとサーバーの通信には、RPC 型を活用します

アンチパターン

• ❌ ルートの後にロガーミドルウェアを適用する（それらのルートはログに記録されません）
• ❌ ミドルウェアで await next() を忘れる（ミドルウェアチェーンが機能しなくなります）
• ❌ 特定のルートだけに cors() を使用する（プリフライトリクエストにはグローバルな CORS が必要です）
• ❌ リクエストボディを複数回解析する（最初の解析後にキャッシュします）
• ❌ パスパラメーターを検証しない（ユーザー入力は必ず検証します）
• ❌ 適切な Hono のジェネリクスの代わりに any 型を使用する
• ❌ CORS 設定でオリジンをハードコードする（環境変数を使用します）
• ❌ エラーハンドラーがない（未処理の Promise 拒否につながります）
• ❌ ランタイムアダプター向けのアプリのエクスポートを忘れる

フィードバックループ

エンドポイントのテスト:

curl -X GET http://localhost:3000/api/users
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"[email protected]"}'

バリデーションのテスト:

# Should return 400 with validation details
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"","email":"invalid"}'

パフォーマンステスト:

pnpm add -D autocannon
npx autocannon -c 100 -d 10 http://localhost:3000/api/users
# Target: <10ms p99 latency for simple endpoints