cloudflare

Cloudflare

概要

Cloudflare Workers は、Cloudflare のグローバルネットワーク上で JavaScript、TypeScript、WebAssembly を実行するサーバーレスのエッジコンピューティングプラットフォームです。Workers は fetch、scheduled、queue イベントハンドラーを使用する ES モジュール形式で動作し、環境バインディングを通じてプラットフォームサービス（KV、D1、R2、Durable Objects）にアクセスします。

使用する場面： エッジファーストの API、低レイテンシのグローバルアプリ、サーバーレス関数、Pages を使った静的サイトのホスティング、キーバリューキャッシュ、エッジでのリレーショナルデータ、エグレス料金のかからないオブジェクトストレージ。

使用しない場面： CPU 時間制限を超える長時間実行のコンピューティング、永続的な TCP 接続が必要なワークロード、Node.js API との完全な互換性を必要とするアプリケーション、コンテナのほうが適している大規模なモノリシックアプリケーション。

クイックリファレンス

パターン	API / 設定	主なポイント
Fetch ハンドラー	export default { fetch(request, env, ctx) }	HTTP リクエストのエントリーポイント
Scheduled ハンドラー	export default { scheduled(controller, env, ctx) }	設定の [triggers] による Cron トリガー
環境変数	env.VAR_NAME	wrangler.toml またはダッシュボードで設定
KV の読み取り／書き込み	env.KV.get(key) / env.KV.put(key, value)	結果整合性、値の最大サイズは 25 MiB
D1 クエリ	env.DB.prepare(sql).bind(...params).all()	エッジ上の SQLite、プリペアドステートメント
D1 バッチ	env.DB.batch([stmt1, stmt2])	アトミックなトランザクション、単一のラウンドトリップ
R2 アップロード	env.BUCKET.put(key, body)	S3 互換、エグレス料金なし
R2 ダウンロード	env.BUCKET.get(key)	ReadableStream を含む R2ObjectBody を返します
Durable Objects	env.DO.get(id) の後に stub.fetch(request)	単一インスタンスによるステートフルな調整
DO ストレージ	this.ctx.storage.sql.exec(query)	新しい DO では SQLite バックエンドを推奨
Pages のデプロイ	wrangler pages deploy <dir>	静的コンテンツと Functions、自動生成されるルート
Worker のデプロイ	wrangler deploy	設定に wrangler.toml を読み込みます
開発サーバー	wrangler dev	バインディングを使ったローカル開発
シークレット	wrangler secret put SECRET_NAME	暗号化され、wrangler.toml には保存されません
静的アセット	assets: { directory: "./dist" }	デフォルトでは Worker を呼び出さずに配信されます
Workflows	export class MyWorkflow extends WorkflowEntrypoint	永続的なマルチステップ実行エンジン
Hyperdrive	env.HYPERDRIVE.connectionString	外部 PostgreSQL のコネクションプーリング
Queues による送信	env.QUEUE.send(message)	Workers 間の非同期メッセージパッシング
設定形式	wrangler.jsonc（新規プロジェクトで推奨）	コメント付き JSON。TOML より推奨

よくある間違い

間違い	正しいパターン
バインディングにグローバル変数としてアクセスする	モジュール形式では env パラメーターを介してアクセスする
シークレットを wrangler.toml に保存する	暗号化された値には wrangler secret put を使用する
強い一貫性が必要な用途に KV を使用する	一貫性のある読み取りには D1 または Durable Objects を使用する
D1 クエリでパラメーターをバインドしない	SQL インジェクションを防ぐため、必ず .prepare().bind() を使用する
KV の値のサイズ上限（25 MiB）を超える	25 MiB を超えるオブジェクトには R2 を使用する
ストレージ操作で await を忘れる	KV、D1、R2 のメソッドはすべて非同期です
signal を渡さずに fetch() を使用する	自動キャンセルのために request.signal を渡す
Worker コード内で D1 データベースを作成する	wrangler d1 create で作成し、設定でバインドする
設定に compatibility_date がない	破壊的変更を避けるため、必ず設定する
fetch ハンドラーから Response 以外を返す	Response オブジェクトを返す必要があります
新しいプロジェクトで wrangler.toml を使用する	新しいプロジェクトでは wrangler.jsonc を使用する。IDE のサポートが優れています
リレーショナルクエリに KV を使用する	SQL クエリには D1 を使用する。KV はキーと値のみを扱います

委任

• アーキテクチャレビュー：Task エージェントを使用して、エッジとオリジンのパターンを評価します
• コードレビュー：code-reviewer エージェントに委任します
• ストレージの選定：Explore エージェントを使用して、KV、D1、R2、DO を比較します

参考資料

• Workers の構文、fetch ハンドラー、スケジュールイベント、バインディング
• KV、D1、R2、Durable Objects のストレージ API
• Cloudflare Pages、関数、ルート、ビルド設定
• Wrangler CLI、設定、開発サーバー、デプロイ、シークレット