cloudflare-worker

Cloudflare Workers

TypeScript Workers の開発パターンです。

関連スキル（majestic-devops）：

• wrangler-coder：CLI によるデプロイ、シークレット、テスト、複数環境
• cloudflare-coder：Terraform/OpenTofu によるインフラストラクチャのプロビジョニング

基本原則

エッジファーストの考え方

• デフォルトではステートレス：Workers はリクエスト間で状態を保持しません
• グローバルに分散：コードは世界中の 300 以上のデータセンターで実行されます
• コールドスタートを最適化：V8 アイソレートは数ミリ秒で起動します
• リクエスト／レスポンスモデル：各呼び出しで 1 つのリクエストを処理します

ストレージの選択

ストレージ	用途	一貫性	レイテンシ
KV	設定、フラグ、キャッシュデータ	結果整合性	約10ms
D1	リレーショナルデータ、トランザクション	強い（一つのリージョン内）	約30～50ms
R2	ファイル、画像、大容量オブジェクト	強い	約50～100ms
Durable Objects	リアルタイム状態、WebSockets	強い（オブジェクト単位）	約50ms
Queues	非同期処理、バッチ処理	少なくとも1回	非同期

プロジェクト構成

my-worker/
├── src/
│   ├── index.ts          # Entry point
│   ├── routes/           # Route handlers
│   ├── services/         # Business logic
│   └── types.ts          # Type definitions
├── test/
├── wrangler.toml         # Cloudflare config
├── package.json
└── tsconfig.json

クイックスタート

最小限の wrangler.toml

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

すべてのバインディングを含む完全な設定については、references/setup.md を参照してください。

基本的な Hono アプリ

import { Hono } from 'hono';
import { Env } from './types';

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

app.get('/', (c) => c.json({ status: 'ok' }));
app.onError((err, c) => c.json({ error: 'Internal Error' }, 500));
app.notFound((c) => c.json({ error: 'Not Found' }, 404));

export default app;

ルートの整理とミドルウェアのパターンについては、references/hono.md を参照してください。

ストレージのクイックリファレンス

KV（キー・バリュー）

await env.CACHE.get('key', 'json');
await env.CACHE.put('key', value, { expirationTtl: 3600 });
await env.CACHE.delete('key');

D1（SQLite）

const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(id).first();

R2（オブジェクトストレージ）

await env.STORAGE.put('path/file.json', JSON.stringify(data));
const object = await env.STORAGE.get('path/file.json');

キャッシュのパターン、マイグレーション、クエリについては、references/storage.md を参照してください。

Durable Objects

リアルタイム連携、WebSockets、レート制限、分散ロックに使用します。

// Get DO stub
const id = c.env.COUNTER.idFromName('my-counter');
const stub = c.env.COUNTER.get(id);
const response = await stub.fetch(new Request('http://do/increment'));

WebSocket Hibernation を含む完全なパターンについては、references/durable-objects.md を参照してください。

Queues

// Producer
await env.QUEUE.send({ type: 'email', payload: { to: '[email protected]' } });

// Consumer (add to default export)
async queue(batch: MessageBatch, env: Env) {
  for (const msg of batch.messages) {
    try { await process(msg.body); msg.ack(); }
    catch { msg.retry(); }
  }
}

コンシューマーのパターンとテストのセットアップについては、references/queues-testing.md を参照してください。

CLI コマンド

# Development
wrangler dev                    # Start local server
wrangler dev --remote           # Dev with remote bindings

# Deploy
wrangler deploy

# D1
wrangler d1 migrations apply my-database

# Secrets
wrangler secret put API_KEY

# Logs
wrangler tail

アンチパターン

避けること	代わりに使うこと
Service Worker 形式	ES モジュール
キャッシュ書き込みを await する	ノンブロッキング処理には waitUntil
大きな KV 値（>25MB）	ファイルには R2
WebSockets に server.accept() を使う	ctx.acceptWebSocket()（Hibernation API）
アナリティクス／ログ処理でブロックする	バックグラウンドタスクには waitUntil
KV の即時整合性を前提にする	一貫性が重要な場合は D1 または DOs

リソース

• Cloudflare Workers ドキュメント
• Hono ドキュメント
• D1 ドキュメント
• Durable Objects ガイド