HonoとTypeScriptで構築する軽量・型安全なREST API:Cloudflare WorkersからNode.jsまで

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

背景:エッジファースト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コンテナ、そして世界中のエッジネットワーク上でシームレスに動作する、単一かつ型安全なコードベースを手に入れることができます。

Share: