総合演習 — ミニ SaaS を丸ごと作る

プロジェクトを作成し、D1・KV・R2・Queues のリソースを作って 1 枚の wrangler.jsonc に束ねます。所要時間は 15 分程度です。

1. プロジェクトを作成する（テンプレートは Hello World / Worker only / TypeScript を選択）

npm create cloudflare@latest -- clip-summarizer
cd clip-summarizer

2. 4 つのリソースを作成する。d1 create と kv namespace create の出力に表示される database_id / id を控えておく

npx wrangler d1 create clip-db
npx wrangler kv namespace create CACHE
npx wrangler r2 bucket create clip-bodies
npx wrangler queues create summarize-jobs

3. wrangler.jsonc を次の内容に置き換える。<YOUR_DATABASE_ID> と <YOUR_NAMESPACE_ID> は手順 2 で控えた値に置き換える

{
  "name": "clip-summarizer",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-10",
  "assets": { "directory": "./public", "binding": "ASSETS" },
  "d1_databases": [
    { "binding": "DB", "database_name": "clip-db",
      "database_id": "<YOUR_DATABASE_ID>" }
  ],
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<YOUR_NAMESPACE_ID>" }
  ],
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "clip-bodies" }
  ],
  "queues": {
    "producers": [
      { "binding": "SUMMARIZE_QUEUE", "queue": "summarize-jobs" }
    ],
    "consumers": [
      { "queue": "summarize-jobs", "max_batch_size": 5,
        "max_batch_timeout": 10, "max_retries": 3 }
    ]
  },
  "ai": { "binding": "AI" },
  "triggers": { "crons": ["0 3 * * *"] }
}

4. スキーマファイル schema.sql をプロジェクト直下に作成し、ローカル DB に適用する

CREATE TABLE IF NOT EXISTS clips (
  id TEXT PRIMARY KEY,
  url TEXT NOT NULL,
  title TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  summary TEXT,
  created_at TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_clips_created ON clips (created_at);

npx wrangler d1 execute clip-db --local --file=./schema.sql
npx wrangler types

wrangler types が全バインディングを反映した Env 型を生成すれば成功です。以降のコードはこの型を前提に書きます。

投稿を受けて 3 つのストレージへ書き分け、要約ジョブをキューに積む producer 側を実装します。

1. src/index.ts をルーター骨格に置き換える。queue / scheduled は後のハンズオンで埋める

type QueueJob = { clipId: string };

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const { pathname } = new URL(request.url);
    if (pathname === "/api/clips" && request.method === "POST") {
      return createClip(request, env);
    }
    if (pathname === "/api/clips" && request.method === "GET") {
      return listClips(env);
    }
    if (pathname.startsWith("/api/clips/") && request.method === "GET") {
      return getClip(pathname.slice("/api/clips/".length), env, ctx);
    }
    if (pathname.startsWith("/s/")) {
      return redirectShortUrl(pathname.slice(3), env);
    }
    return env.ASSETS.fetch(request); // それ以外は静的アセットに委譲
  },
  async queue(batch, env, ctx): Promise<void> { /* ハンズオン 17-3 */ },
  async scheduled(controller, env, ctx) { /* ハンズオン 17-4 */ },
} satisfies ExportedHandler<Env, QueueJob>;

2. 投稿処理を実装する。「R2 に本文 → D1 にメタデータ → KV に短縮 URL → キューにジョブ」の順に書き、要約を待たずに応答する

async function createClip(request: Request, env: Env): Promise<Response> {
  const { url, title, body } = (await request.json()) as {
    url: string; title: string; body: string;
  };
  const id = crypto.randomUUID();
  await env.BUCKET.put(`clips/${id}.txt`, body);
  await env.DB.prepare(
    "INSERT INTO clips (id, url, title, status, created_at) VALUES (?, ?, ?, 'pending', ?)",
  ).bind(id, url, title, new Date().toISOString()).run();
  await env.CACHE.put(`s:${id.slice(0, 8)}`, url, {
    expirationTtl: 60 * 60 * 24 * 30, // 短縮 URL は 30 日で自動失効
  });
  await env.SUMMARIZE_QUEUE.send({ clipId: id }); // 128 KB までの JSON
  return Response.json(
    { id, shortCode: id.slice(0, 8), status: "pending" },
    { status: 201 },
  );
}

async function listClips(env: Env): Promise<Response> {
  const { results } = await env.DB.prepare(
    "SELECT id, url, title, status, summary, created_at FROM clips ORDER BY created_at DESC LIMIT 50",
  ).run();
  return Response.json(results);
}

3. npx wrangler dev を起動し、curl で投稿して確認する

curl -X POST http://localhost:8787/api/clips \
  -d '{"url":"https://example.com/a","title":"テスト記事","body":"本文..."}'
# => {"id":"...","shortCode":"...","status":"pending"}

GET /api/clips で status: "pending" の行が返れば成功です。要約はまだ生成されません（consumer が空のため）。

queue ハンドラで本文を読み出して LLM 要約を生成し、詳細 API に KV キャッシュを挟みます。

1. 17-2 で空にしておいた queue ハンドラを実装する。メッセージ単位で ack() し、失敗した分だけ再配送させる（第9章の個別制御）

async queue(batch, env, ctx): Promise<void> {
  for (const msg of batch.messages) {
    const { clipId } = msg.body;
    const obj = await env.BUCKET.get(`clips/${clipId}.txt`);
    if (!obj) {
      msg.ack(); // 本文がないジョブは再試行しても無駄なので確定して捨てる
      continue;
    }
    const text = await obj.text();
    const result = (await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      prompt: `次の記事を日本語で 3 文以内に要約してください。\n\n${text.slice(0, 6000)}`,
    })) as { response: string };
    await env.DB.prepare(
      "UPDATE clips SET summary = ?, status = 'done' WHERE id = ?",
    ).bind(result.response, clipId).run();
    msg.ack();
  }
},

2. 詳細 API と短縮 URL リダイレクトを追加する。キャッシュに入れるのは status = 'done' の行だけにする（理由はつまずきポイント参照）

async function getClip(id: string, env: Env, ctx: ExecutionContext): Promise<Response> {
  const cached = await env.CACHE.get(`clip:${id}`, { type: "json", cacheTtl: 300 });
  if (cached) return Response.json(cached);
  const row = await env.DB.prepare("SELECT * FROM clips WHERE id = ?")
    .bind(id).first();
  if (!row) return new Response("Not found", { status: 404 });
  if (row.status === "done") {
    // 応答をブロックしないよう waitUntil で書き込む
    ctx.waitUntil(
      env.CACHE.put(`clip:${id}`, JSON.stringify(row), { expirationTtl: 3600 }),
    );
  }
  return Response.json(row);
}

async function redirectShortUrl(code: string, env: Env): Promise<Response> {
  const dest = await env.CACHE.get(`s:${code}`);
  if (!dest) return new Response("Not found", { status: 404 });
  return Response.redirect(dest, 302);
}

3. wrangler dev を再起動して再度投稿し、数秒待ってから詳細を取得する

curl http://localhost:8787/api/clips/<ID>
# => {"id":"...","status":"done","summary":"この記事は…",...}

status が done になり summary に日本語要約が入っていれば、Queues → Workers AI → D1 のパイプラインが通っています。/s/<shortCode> が元 URL へ 302 リダイレクトすることも確認してください。

UI と定期クリーンアップを足して全部品を揃え、本番デプロイして wrangler tail で観測します。

1. public/index.html を作成する（最小限のフォームと一覧）

<!doctype html>
<html lang="ja">
<meta charset="utf-8" />
<title>Clip Summarizer</title>
<body>
  <h1>Clip Summarizer</h1>
  <form id="clip-form">
    <input name="url" placeholder="https://example.com/article" required />
    <input name="title" placeholder="タイトル" required />
    <textarea name="body" placeholder="本文を貼り付け" required></textarea>
    <button>クリップする</button>
  </form>
  <ul id="clips"></ul>
  <script>
    const form = document.getElementById("clip-form");
    form.addEventListener("submit", async (e) => {
      e.preventDefault();
      const data = Object.fromEntries(new FormData(form));
      await fetch("/api/clips", { method: "POST", body: JSON.stringify(data) });
      load();
    });
    async function load() {
      const clips = await (await fetch("/api/clips")).json();
      document.getElementById("clips").innerHTML = clips
        .map((c) => `<li>[${c.status}] ${c.title} — ${c.summary ?? "要約待ち"}</li>`)
        .join("");
    }
    load();
  </script>
</body>
</html>

2. scheduled ハンドラを実装する。R2 の delete() は 1 回で最大 1,000 キーまで受け取れる

async scheduled(controller, env, ctx) {
  const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
  const { results } = await env.DB.prepare(
    "SELECT id FROM clips WHERE created_at < ?",
  ).bind(cutoff).run<{ id: string }>();
  if (results.length === 0) return;
  await env.BUCKET.delete(results.map((r) => `clips/${r.id}.txt`));
  await env.DB.prepare("DELETE FROM clips WHERE created_at < ?")
    .bind(cutoff).run();
  console.log(`cleanup: removed ${results.length} clips`);
},

3. cron をローカルで発火させて動作確認する（第3章で学んだ専用ルート）

curl "http://localhost:8787/cdn-cgi/handler/scheduled?format=json"
# => {"outcome":"ok","noRetry":false}

4. 本番の D1 にスキーマを適用してからデプロイし、ログを流し見しながらブラウザで一通り操作する

npx wrangler d1 execute clip-db --remote --file=./schema.sql
npx wrangler deploy
npx wrangler tail --format=pretty

払い出された https://clip-summarizer.<YOUR_SUBDOMAIN>.workers.dev を開いて投稿すると、tail に fetch 呼び出しと queue 呼び出しが順に流れます。ダッシュボードの Workers & Pages → 対象 Worker → Logs → Live でも同じログを確認でき、Cron の実行履歴は Settings 配下の Trigger Events（直近 100 件）で追えます。これで 7 部品すべてが本番で動いています。