背景:エッジファーストAPIへのシフト
長年にわたり、バックエンドサービスを構築する際のデフォルトの選択肢はExpressでした。しかし、サーバーレスアーキテクチャの登場によって状況は一変しました。AWS LambdaやCloud RunにExpressをデプロイすると、40MBにも及ぶコンテナバンドルや肥大化したnode_modules、そして600ミリ秒を超えるコールドスタートとの戦いを強いられることが日常茶飯事でした。さらに悪いことに、レガシーなExpressミドルウェアに厳格なTypeScriptの型を後付けしようとすると、フレームワークそのものと戦っているような感覚に陥ることもしばしばでした。
私たちのチームが低レイテンシが不可欠なマイクロサービスをエッジネットワークに移行した際、従来のNodeスタックでは対応しきれませんでした。Honoはこの課題を直接解決してくれます。モダンなWeb標準(Fetch、Request、Response)に完全に準拠して構築されているHonoは、Cloudflare Workers、Fastly Compute、Deno、Bun、AWS Lambda、そして標準のNode.jsなど、ほぼあらゆるJavaScript環境で動作します。
ライブラリ全体のサイズは最小化(minify)時で14KB未満であり、外部依存関係は一切ありません。代表的な機能であるRegExpRouterは、ルートパターンを正規表現にコンパイルすることで、マイクロ秒単位でパスを解決します。さらにTypeScriptと組み合わせることで、Honoはエンドツーエンドの型安全性とRPCクライアントを提供します。本番環境でAPIの契約破壊(不整合)に気づく代わりに、コンパイラが即座にエラーを検出してくれます。
インストール:マルチランタイムプロジェクトの立ち上げ
Honoには実績のあるプリセットを備えたcreate-honoというスキャフォールディングCLIが用意されています。まずはCloudflare Workersテンプレートから始めることをお勧めします。エッジファーストのコードはNode.jsへスムーズに移植できますが、逆にNode固有のAPI(fsやネイティブストリームなど)をエッジの分離環境(Isolate)で動かすために解きほぐす作業は、非常に骨が折れることで知られているからです。
ステップ1:プロジェクトのスキャフォールディング
対話型セットアップツールを実行し、Cloudflare Workersプリセットを選択します:
npm create hono@latest hono-edge-api
cd hono-edge-api
npm install
ステップ2:バリデーションとNodeアダプターのインストール
次に、Honoの公式バリデータミドルウェアとともにZodをインストールします。また、従来のコンテナ環境でも同一のコードベースを実行できるように、Nodeサーバーアダプターを開発依存関係として追加します:
npm install zod @hono/zod-validator
npm install @hono/node-server @types/node -D
tsconfig.jsonがモダンなECMAScript機能をターゲットにし、厳格な型チェックを有効にしていることを確認します:
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Bundler",
"strict": true,
"skipLibCheck": true,
"types": ["@cloudflare/workers-types"]
}
}
設定:クリーンなルーティングとデュアルデプロイ
Cloudflare WorkersとNode.jsの間でサービスのポータビリティを維持するコツは単純です。ランタイムのリスナーからアプリケーションのルート定義を切り離すことです。
1. スキーマとドメイン型の定義
まずはデータ層から始めましょう。src/schemas.tsでZodを使用してリクエストのバリデーションルールを定義し、TypeScriptの型を推論します:
import { z } from 'zod';
export const CreateArticleSchema = z.object({
title: z.string().min(5, 'タイトルは5文字以上で入力してください'),
slug: z.string().regex(/^[a-z0-9-]+$/, 'スラッグはURLセーフな形式(ケバブケース)である必要があります'),
content: z.string().min(20, 'コンテンツは20文字以上で入力してください'),
published: z.boolean().default(false),
});
export type CreateArticleInput = z.infer<typeof CreateArticleSchema>;
export interface Article extends CreateArticleInput {
id: string;
createdAt: string;
}
2. コアルーターの構築
src/app.tsでルートハンドラーを組み立てます。Honoにはセキュリティヘッダー、CORS、ロギング用の組み込みミドルウェアが備わっているため、HelmetやMorganのようなサードパーティ製パッケージは不要です:
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { secureHeaders } from 'hono/secure-headers';
import { zValidator } from '@hono/zod-validator';
import { CreateArticleSchema, Article } from './schemas';
const articles = new Map<string, Article>();
export const app = new Hono()
.use('*', secureHeaders())
.use('*', cors({
origin: ['https://itfromzero.com'],
allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}))
.get('/api/health', (c) => {
return c.json({
status: 'healthy',
runtime: typeof crypto !== 'undefined' && 'subtle' in crypto ? 'edge-compatible' : 'standard',
timestamp: new Date().toISOString(),
});
})
.get('/api/articles', (c) => {
return c.json(Array.from(articles.values()));
})
.post('/api/articles', zValidator('json', CreateArticleSchema), async (c) => {
const validatedData = c.req.valid('json');
const newArticle: Article = {
id: crypto.randomUUID(),
...validatedData,
createdAt: new Date().toISOString(),
};
articles.set(newArticle.id, newArticle);
return c.json(newArticle, 201);
});
export type AppType = typeof app;
3. Cloudflare Workersのエントリーポイントの設定
Cloudflare Workersは、アプリケーションがESモジュールのデフォルトエクスポートであることを想定しています。src/index.tsはわずか2行に収まります:
import { app } from './app';
export default app;
4. Node.jsサーバーアダプターの追加
まったく同じAPIを標準のDockerコンテナや仮想マシン上で実行するには、src/node-server.tsでルーターを@hono/node-serverでラップします:
import { serve } from '@hono/node-server';
import { app } from './app';
const port = Number(process.env.PORT) || 3000;
console.log(`ポート ${port} でNodeアダプターを起動中...`);
serve({
fetch: app.fetch,
port,
});
次に、開発中に両方のターゲットを並行して実行できるようにpackage.jsonのスクリプトを設定します:
{
"scripts": {
"dev:edge": "wrangler dev",
"deploy:edge": "wrangler deploy",
"dev:node": "tsx watch src/node-server.ts",
"start:node": "node dist/node-server.js"
}
}
検証と可観測性(オブザーバビリティ)
ルーティングとバリデーションが整ったら、ペイロードの制約を検証し、レスポンスヘッダーを確認して、実行時間をプロファイリングできます。
1. Hono Client(RPC)による契約テスト
HonoのRPCクライアント(hc)を使えば、OpenAPIスタブの生成や冗長なクライアントインターフェースの保守が不要になります。エクスポートされたAppTypeをVitestにインポートするだけで、テストの呼び出しが完全に型付けされます:
import { test, expect } from 'vitest';
import { testClient } from 'hono/testing';
import { app } from './src/app';
test('POST /api/articles は不正な入力を拒否し、有効なペイロードを受け入れる', async () => {
const client = testClient(app);
// 不正なペイロード:ZodはHTTP 400 Bad Requestを返す必要がある
const invalidRes = await client.api.articles.$post({
json: {
title: 'Bad',
slug: 'NOT_SAFE!',
content: 'Too short',
published: false,
},
});
expect(invalidRes.status).toBe(400);
// 有効なペイロード:生成されたIDとともにHTTP 201 Createdを返す
const validRes = await client.api.articles.$post({
json: {
title: 'エッジAPIの構築',
slug: 'building-edge-apis',
content: 'モダンなエッジコンピューティングアーキテクチャを探求する実践的チュートリアル。',
published: true,
},
});
expect(validRes.status).toBe(201);
const data = await validRes.json();
expect(data.id).toBeDefined();
});
2. ターミナルでのクイックスモークテスト
npm run dev:edgeでローカルワーカーを起動し(デフォルトはポート8787)、cURLを使ってエンドポイントを直接テストします:
# 1. ヘルスチェックとランタイムの確認
curl -i http://localhost:8787/api/health
# 2. 必須フィールド不足による400エラーの発生
curl -i -X POST http://localhost:8787/api/articles \
-H "Content-Type: application/json" \
-d '{"title": "Tiny"}'
# 3. 有効な記事レコードの作成
curl -i -X POST http://localhost:8787/api/articles \
-H "Content-Type: application/json" \
-d '{"title": "TypeScript on the Edge", "slug": "typescript-edge", "content": "型安全なサーバーレスAPIを構築するための実践ガイド。", "published": true}'
3. エッジテレメトリとタイミングヘッダー
ダウンストリームの処理でボトルネックが発生してしまっては、ミリ秒未満の高速ルーティングも活かせません。リクエストの所要時間をキャプチャし、標準のServer-Timingヘッダー経由で公開する軽量なタイミングミドルウェアを追加しましょう:
app.use('*', async (c, next) => {
const start = performance.now();
await next();
const elapsed = (performance.now() - start).toFixed(2);
c.header('Server-Timing', `total;dur=${elapsed}`);
console.log(`[HTTP] ${c.req.method} ${c.req.path} -> ${c.res.status} (${elapsed}ms)`);
});
Cloudflare Workers上では、コールドスタートは5ミリ秒未満に抑えられ、キャッシュ済みルートやインメモリルートの中央値実行時間は2ミリ秒を下回ります。これにより、ローカルの開発マシン、Dockerコンテナ、そして世界中のエッジネットワーク上でシームレスに動作する、単一かつ型安全なコードベースを手に入れることができます。
