HonoとCloudflare Workersで作る超軽量Web API:Type-safeルーティング、ミドルウェア、Serverless Edge

Development tutorial - IT technology blog
Development tutorial - IT technology blog

1ヶ月稼働させても誰も呼ばない――それでもサーバー代はかかる

チームの内部ツール用に小さなAPIを書いたとしよう。webhookを受け取り、データを処理して、JSONを返す。複雑ではない、エンドポイントは数個だけ。でもデプロイするには、24/7稼働するサーバーが必要で、Node.jsをインストールし、Nginxを設定し、SSLの管理、セキュリティアップデートの対応……月末には実際のトラフィックが数百リクエストしかなくても、VPS代を払い続ける。

自分はこれを3年近くやっていた。月5ドルのVPSで、月間リクエスト数が10,000にも満たないExpressアプリを動かしていた。効率的か?いや。別の方法はあるか?ある。

本質的な問題:Express + VPSが常に正しい選択とは限らない

Express.jsはサーバーがまだ物理マシンだった時代に生まれた。単一のNode.jsプロセスがすべてのリクエストを処理するモデルは、大規模なWebアプリには今でも理にかなっている――データベースのコネクションプール、セッション管理、フルスタックのミドルウェアが必要な場合などだ。そういった用途ではExpressは十分機能する。

しかし小さなAPI――webhookハンドラー、シンプルなプロキシ、認証サービス、レートリミッター――では、「常時稼働サーバー」モデルがいくつかの実際的な問題を生む:

  • アイドルコストが馬鹿にならない:サーバーが何もしていなくてもRAM、CPU、そしてお金がかかる。
  • 手動スケーリング:トラフィックが急増した場合、自分でインスタンスやロードバランサーを追加しなければならない。
  • 固定されたロケーション:サーバーはシンガポールにあるのにユーザーはアメリカにいる――レイテンシが必要以上に高くなる。
  • 運用オーバーヘッド:OSのアップデート、プロセスクラッシュの監視、バックアップ――すべて自分で対応しなければならない。

代替の選択肢:Lambda、Vercel Functions、それともCloudflare Workers?

最もシンプルな解決策:コードが実際に実行されたときだけお金を払う。Serverless functionsがそれを実現してくれる――ただし各プラットフォームで実装が異なり、トレードオフも違う:

  • AWS Lambda:強力で柔軟だが、Node.jsではコールドスタートが1〜2秒かかることがある。IAM、VPC、API Gatewayの設定は実際のニーズより大幅に複雑だ。
  • Vercel/Netlify Functions:よりシンプルで、フロントエンドとの統合が良好。ただし実行時間に制限があり(無料プランで10秒)、リクエストはまだ固定リージョンに向かう。
  • Cloudflare Workers:Node.jsプロセスの代わりにV8 isolatesで動作する。コールドスタートは5ms未満。世界300以上のPoP上にデプロイ。無料プランで1日10万リクエスト。

Cloudflare Workersが他の2つと根本的に異なる点:Node.jsランタイムではなくV8 isolatesを使用している――Chromeと同じエンジンだが、数百ミリ秒ではなく数ミリ秒で起動する。トレードオフとして完全なNode.js API(fs、netは使用不可)はないが、通常のWeb APIではそれが問題になることはほとんどない。

Hono:モダンWeb APIのための最軽量フレームワーク

Hono(日本語:炎)はedgeランタイム向けに最初から設計されたWebフレームワークだ:Cloudflare Workers、Deno、Bun、そしてNode.jsにも対応している。ExpressライクなAPIで書き慣れた感覚があるが、よりtype-safeで、軽量(約14KB)で、プラットフォームごとに個別のアダプターを書く必要がない。

個人的に最も気に入っている点:HonoはNode.js環境にいるふりをしない。Web標準API――Request、Response、Headers――を使用しており、ブラウザ、Deno、Bunがそのまま理解できるWeb標準だ。

プロジェクトの初期化

# Cloudflare Workersテンプレートで新規プロジェクトを作成
npm create hono@latest my-api
# 選択: cloudflare-workers

cd my-api
npm install

初期ディレクトリ構成:

my-api/
├── src/
│   └── index.ts       # Entry point
├── wrangler.toml      # Cloudflare Workers config
├── package.json
└── tsconfig.json

基本ルーティングとType-safeレスポンス

src/index.ts ファイル:

import { Hono } from 'hono'

const app = new Hono()

// シンプルなルート
app.get('/', (c) => c.text('Hello from Edge!'))

// パスパラメータ付きルート — type-safe
app.get('/users/:id', (c) => {
  const id = c.req.param('id')  // TypeScriptは`id`がstringだと認識する
  return c.json({ userId: id, status: 'active' })
})

// POST bodyを受け取るルート
app.post('/webhooks/github', async (c) => {
  const payload = await c.req.json()
  const event = c.req.header('X-GitHub-Event')

  if (event === 'push') {
    console.log('Push to:', payload.repository?.full_name)
  }

  return c.json({ received: true }, 200)
})

export default app

ミドルウェアの追加:Authentication、CORSとLogging

組み込みミドルウェアはHonoの強みだ――追加のnpm installは不要。Bearer token認証、CORSとloggingの例:

import { Hono } from 'hono'
import { bearerAuth } from 'hono/bearer-auth'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'

const app = new Hono()

// グローバルミドルウェア — すべてのルートに適用
app.use('*', logger())
app.use('*', cors({
  origin: ['https://yourdomain.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
}))

// 保護されたルート — /api/*にのみ適用
app.use('/api/*', bearerAuth({ token: 'your-secret-token' }))

app.get('/api/data', (c) => {
  return c.json({ message: 'Protected data', timestamp: Date.now() })
})

// パブリックルート — 認証不要
app.get('/health', (c) => c.json({ ok: true }))

export default app

環境変数とSecrets

Cloudflare WorkersのSecretsはNode.jsとは異なる――従来の.envファイルはない。代わりにWranglerを使って直接設定する:

# CLIでsecretを設定する(プロンプトで値を入力)
npx wrangler secret put API_SECRET_KEY

# wrangler.toml — 通常の変数を宣言(secretではない)
[vars]
ENVIRONMENT = "production"

type-safe bindingsでコード内からアクセスする:

// environment bindingsの型を宣言
type Bindings = {
  API_SECRET_KEY: string
  ENVIRONMENT: string
}

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

app.get('/config', (c) => {
  // c.envは完全な型を持つ — IDEが正しい変数名を補完する
  return c.json({ environment: c.env.ENVIRONMENT })
})

プロジェクトが大きくなったらルートをモジュール分割する

// src/routes/users.ts
import { Hono } from 'hono'

const users = new Hono()

users.get('/', (c) => c.json({ users: [] }))
users.get('/:id', (c) => c.json({ id: c.req.param('id') }))
users.post('/', async (c) => {
  const body = await c.req.json()
  return c.json({ created: true, data: body }, 201)
})

export default users
// src/index.ts — サブルーターをマウントする
import { Hono } from 'hono'
import users from './routes/users'
import webhooks from './routes/webhooks'

const app = new Hono()

app.route('/users', users)       // /users, /users/:id
app.route('/webhooks', webhooks) // /webhooks/github, /webhooks/stripe

export default app

ローカルテストとデプロイ

# ホットリロード付きでローカル実行
npx wrangler dev
# APIはhttp://localhost:8787で起動

# Cloudflareにデプロイ(初回はログインが必要)
npx wrangler login
npm run deploy

# 出力:
# ✅ Deployed to: https://my-api.your-username.workers.dev

デプロイ前は、Wrangler devでローカルテストをしてからレスポンスをtoolcraft.app/ja/tools/developer/json-formatterにコピーしてJSONの構造を確認している――ターミナルでrawを読んだり拡張機能をインストールしたりするより格段に楽だ。特にネストが深いレスポンスは、整形して表示することでデバッグが圧倒的にスムーズになる。

デプロイ全体のプロセスは約10〜15秒で完了する。サーバーの設定は不要、SSLの心配もない(Cloudflareが自動で処理)、NginxやPM2のセットアップも必要ない。

実際の結果:月5ドルのVPSからほぼ0ドルへ

いくつかの内部APIをVPSからCloudflare Workersに移行した後、すぐにいくつかの違いに気づいた:

  • 無料プランで1日10万リクエスト――ほとんどの内部ツールや小規模webhookハンドラーには十分
  • リクエストが最寄りのPoPで処理されるため、複数リージョンのユーザーに対してレイテンシが低減
  • ゼロメンテナンス:OSアップデートの心配なし、夜中3時のプロセスクラッシュの心配なし
  • デプロイとロールバックはコマンド一つ、Cloudflareがデプロイ履歴を保持

ただし、Cloudflare Workersが適切でないケースもある。APIが複雑なコネクションプーリングでPostgresに接続する必要がある場合、long-runningなプロセスが必要な場合、ファイルシステムへのアクセスが必要な場合――これらは従来のサーバーが依然として必要だ。一方、webhookハンドラー、APIプロキシ、認証サービス、レートリミッターには逆に向いている――24時間365日アイドル状態のVPSより遥かにすっきりする。

最も現実的な出発点:VPSで動いているwebhookハンドラーをひとつ取り出し、Honoに移植してCloudflare Workersにデプロイする。2〜3時間で完了し、そのVPSはなぜこんなに長く持ち続けていたのかと自問することになるだろう。

Share: