第14章：Hono・Service Bindings・RPCで“整理されたAPI”へ進もう 🧱🧠

この章では、今まで作ってきたAPIを「ただ動くもの」から「育てやすいもの」へ進化させます 🌱 第13章でAI APIを1本作れたなら、次は 役割ごとに分ける、内部だけで呼ぶ、型で事故を減らす、この3つを覚える番です。Cloudflare公式でも、外に見せる入口と内部処理を分ける設計はとても相性がよく、複数Workerを Service Bindings + type-safe RPC でつなぐ構成が案内されています。 (Cloudflare Docs)

この章のゴール 🎯📘

この章を終えると、次のことができるようになります。

Hono を使って、外向きAPIのルーティングを見やすく整理できる 😊 (Cloudflare Docs)
Service Bindings を使って、Workerから別Workerを 公開URLなし で呼べる 🚪➡️🚪 (Cloudflare Docs)
RPC を使って、内部Workerのメソッドを 関数っぽく直接呼ぶ 感覚をつかめる ⚡ (Cloudflare Docs)
Workers AI や AI Gateway を、外向きAPIの裏側にきれいに隠して扱える 🤖🌐 (Cloudflare Docs)
wrangler types を使って、binding名ミスや型ズレを早めに見つけられる 🛟 (Cloudflare Docs)

この章で作る完成イメージ 🏗️✨

今回の完成イメージはこんな感じです。

ブラウザ / React画面 → Honoで作った公開API Worker → 内部専用のAI Worker → Workers AI / AI Gateway / 将来はD1やVectorizeも追加

この分け方にすると、ユーザーが叩くのは公開API Workerだけです。AIの呼び出し方、モデルの差し替え、ログ収集、将来のRAG化などは内部Worker側で吸収しやすくなります。CloudflareのAI関連ドキュメントでも、Workers AI・AI Gateway・Vectorize を組み合わせた構成が案内されています。 (Cloudflare Docs)

まずは3つの道具をやさしく整理しよう 🧰🌈

1. Honoって何？ 🍜

Hono は、Cloudflare Workers と相性のよい軽量フレームワークです。Cloudflare公式では、React SPA + Hono API + Cloudflare Vite plugin の組み合わせで始める例も出ていて、ローカル開発時も Workers 本番に近いランタイムで動かしやすい流れになっています。 (Cloudflare Docs)

この章では、Honoを「外向きAPIの受付係」として使います。たとえば、

POST /api/summary
POST /api/classify
GET /api/health

みたいに、ブラウザやReactから呼ばれる入口をHonoでまとめます 😊

2. Service Bindingsって何？ 🔗

Service Bindings は、Worker A から Worker B を内部接続で呼ぶ仕組みです。Cloudflare公式では、publicly-accessible URL を通さない、zero overhead / added latency がない、追加コストなし と説明されています。さらにベストプラクティスでも、Worker同士の通信は公開URLではなく Service Bindings を使うよう案内されています。 (Cloudflare Docs)

大事なのはここです👇

外向きURLをわざわざ叩かなくていい 🌐❌
内部用Workerを 外に公開しなくて済む 🔒
機能ごとに分割しても遅くなりにくい ⚡
「認証」「AI」「DB」などを役割別に切り分けやすい 🧩

3. RPCって何？ ☎️✨

CloudflareのRPCは、内部Workerのメソッドを JavaScriptの関数みたいに呼べる 仕組みです。公式では WorkerEntrypoint を継承して公開メソッドを作り、呼び出し側Workerは binding 経由でそのメソッドを直接呼びます。たとえば公式例では、片方のWorkerが add(a, b) を公開し、呼び出し側が env.WORKER_B.add(1, 2) のように使えます。 (Cloudflare Docs)

つまり、HTTPのURLを自分で組み立てて fetch する代わりに、

env.AI_CORE.summarizeJapanese(text)
env.AUTH_SERVICE.validate(token)

みたいに呼べるわけです 😍 この感覚がつかめると、一気に「整理された設計」が見えてきます。

HTTPのService BindingとRPCの違い 🆚🧠

ここ、初学者が混ざりやすいので整理します。

HTTPでつなぐ場合 🌐

binding先の fetch() を呼びます。Cloudflare公式でも env.WORKER_B.fetch(request) という形で説明されています。HTTPのRequest/Responseをそのまま流したいときに向いています。 (Cloudflare Docs)

RPCでつなぐ場合 ⚡

binding先の 公開メソッド を直接呼びます。Cloudflare公式では、WorkerEntrypoint の公開メソッドを別Workerから直接呼べるようになっています。処理単位がはっきりしていて、TypeScriptで安全に扱いたいときにかなり便利です。 (Cloudflare Docs)

今回の章ではどっちを採用する？

外向きは Hono + HTTPっぽいAPI、内向きは Service Bindings + RPC がいちばん学習効果が高いです 😊 利用者には普通のAPIとして見せつつ、内部はきれいに関数呼び出しのように整理できます。

この章のおすすめ設計 🏛️✨

この章では、こう考えるとスッと入ります。

公開API Workerの役目 🌍

ルーティング
入力チェック
エラー整形
認証チェック
レスポンス形式の統一

内部AI Workerの役目 🤖

要約
分類
文章整形
AI Gatewayのログやキャッシュ設定
将来のモデル差し替え

Cloudflareの配置ガイドでも、認証やルーティングなどの edge logic と、DB問い合わせやAPI呼び出しなどの back-end logic を複数Workerに分け、Service Bindings と type-safe RPC でつなぐ構成が案内されています。 (Cloudflare Docs)

ハンズオン：公開API Worker と内部AI Worker を分けてみよう 🛠️🤖

ここからが実践です 💪✨ 今回はシンプルに、2つのWorkerを用意します。

api-worker … Honoで公開APIを受ける
ai-core … 内部専用。Workers AI を呼ぶ

Cloudflare公式では新規プロジェクトでは wrangler.jsonc 推奨です。新しい機能はJSON設定を前提にしているものもあるので、この章でも JSONC で進めます。 (Cloudflare Docs)

手順1：内部AI Worker を作る 🤖

まずはAI処理専用のWorkerです。ここは外から直接触らせない「中身」にします。

ai-core / wrangler.jsonc

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "ai-core",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-17",
  "ai": {
    "binding": "AI"
  }
}

Workers AI は AI binding を追加すると Worker から env.AI として使えます。Cloudflare公式でも、この形で binding を追加して env.AI.run() を呼ぶ流れが案内されています。 (Cloudflare Docs)

ai-core / src/index.ts

import { WorkerEntrypoint } from "cloudflare:workers";

type TextResult = {
  text: string;
};

export default class AiCore extends WorkerEntrypoint<Env> {
  async summarizeJapanese(input: string): Promise<TextResult> {
    const result = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      prompt: `次の文章を日本語でやさしく3行以内に要約してください。\n\n${input}`,
    });

    return {
      text: String((result as { response?: string }).response ?? ""),
    };
  }

  async classifyJapanese(input: string): Promise<TextResult> {
    const result = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      prompt: `次の文章を「質問」「感想」「要望」のどれか1語で分類してください。\n\n${input}`,
    });

    return {
      text: String((result as { response?: string }).response ?? ""),
    };
  }
}

ここでのポイントは、fetch ハンドラではなくメソッドを公開している ことです。

WorkerEntrypoint exposing internal RPC methods

このWorkerは「URLを受ける窓口」より、「内部から呼ばれる道具箱」っぽい存在です。Cloudflare公式でも、WorkerEntrypoint を継承して公開メソッドを作る のがRPCの基本形です。 (Cloudflare Docs)

手順2：公開API Worker に Service Binding を付ける 🌍➡️🤖

次は、外に見せる側です。こちらは Hono を使って、入口をスッキリ整理します。

api-worker / wrangler.jsonc

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "api-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-17",
  "services": [
    {
      "binding": "AI_CORE",
      "service": "ai-core"
    }
  ]
}

ここで超大事なのは、Service Binding は呼び出し側の Wrangler 設定に書く ことです。

Service Binding connection between Workers

Cloudflare公式でも、Service Binding は caller 側 に追加すると説明されています。 (Cloudflare Docs)

手順3：Honoで公開APIを作る 🍜✨

api-worker / src/index.ts

import { Hono } from "hono";

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

app.get("/api/health", (c) => {
  return c.json({ ok: true });
});

app.post("/api/summary", async (c) => {
  const body = await c.req.json<{ text?: string }>();

  if (!body.text) {
    return c.json({ error: "text は必須です" }, 400);
  }

  const result = await c.env.AI_CORE.summarizeJapanese(body.text);
  return c.json({ summary: result.text });
});

app.post("/api/classify", async (c) => {
  const body = await c.req.json<{ text?: string }>();

  if (!body.text) {
    return c.json({ error: "text は必須です" }, 400);
  }

  const result = await c.env.AI_CORE.classifyJapanese(body.text);
  return c.json({ label: result.text });
});

export default app;

Hono 側はかなり読みやすいですね 😊 「どのURLを受けるか」「入力が足りないときどう返すか」「内部AI Workerのどの処理を呼ぶか」が、かなり素直に見えるはずです。

Cloudflare公式のHonoガイドでも、Honoアプリは Worker 上で動き、binding を通じて compute / storage / AI などと統合できる形が案内されています。さらに Vite plugin により、ローカル開発も本番に近いWorkersランタイムで試しやすくなっています。 (Cloudflare Docs)

手順4：型を自動生成する 🧠🛟

Service Bindings と RPC を使うなら、wrangler types はほぼ必須です。

Auto-generating types for RPC

Cloudflare公式では、Env を手書きしないで wrangler types を使う ことがベストプラクティスとして案内されています。binding を追加・変更したら再実行するのが大事です。 (Cloudflare Docs)

たとえばワークスペースでこうします。

npx wrangler types -c ./api-worker/wrangler.jsonc -c ./ai-core/wrangler.jsonc

Cloudflare公式のRPC TypeScriptガイドでも、複数の Wrangler 設定ファイルを指定して型を生成すると、Service<...> を含む正しい型が作られ、env.SUM_SERVICE.sum(...) のようなRPCメソッドが型付きで扱えると説明されています。 (Cloudflare Docs)

手順5：動かして確認する ▶️✨

ローカルで開発するとき、Cloudflare公式のHonoガイドでは Cloudflare Vite plugin によって Workers runtime に近い形 で動かせて、binding のローカルエミュレーションも使えると案内されています。 (Cloudflare Docs)

確認したい流れはこんな感じです。

POST /api/summary に文章を送る
Hono がJSONを受け取る
c.env.AI_CORE.summarizeJapanese(...) を呼ぶ
内部AI Worker が env.AI.run() で要約する
結果を Hono が整えて返す

この時点で、外からは普通のAPIに見えるのに、内部はかなり整理されています 🎉

さらに一歩：AI Gateway を混ぜるともっと今っぽい 🚀🤖

Cloudflare公式では、AI binding の env.AI から AI Gateway の機能を直接使えます。 AI Gateway には analytics / logging / caching / rate limiting / retries / fallback などがあり、AIアプリの観測と制御に向いています。Workers AI モデルも、AI binding 経由で Gateway オプションを付けて実行できます。 (Cloudflare Docs)

たとえば内部AI Workerだけをこう変えると、公開APIの形を変えずに、AIログやキャッシュ制御を足せます。

Integrating AI Gateway internally

const result = await this.env.AI.run(
  "@cf/moonshotai/kimi-k2.5",
  {
    prompt: `次の文章を日本語で要約してください。\n\n${input}`,
  },
  {
    gateway: {
      id: "chapter14-gateway",
      collectLog: true,
      cacheTtl: 300,
    },
  },
);

こういう分離にしておくと、将来、

モデル変更 🔄
AI Gateway導入 📊
VectorizeによるRAG化 📚
D1で履歴保存 🧾

みたいな拡張がしやすいです。CloudflareのAIユースケースでも、Workers + Workers AI / AI Gateway + Vectorize の組み合わせが案内されています。 (Cloudflare Docs)

named entrypoints を知ると、さらに整理上手になれる 🏷️✨

Cloudflare公式のRPCドキュメントでは、1つのWorker内に 複数の WorkerEntrypoint を定義し、Service Binding 側で entrypoint を指定して特定の役割だけを呼ぶ形も紹介されています。たとえば AdminEntrypoint のように、管理者用の機能だけ切り出せます。 (Cloudflare Docs)

たとえばイメージはこんな感じです。

import { WorkerEntrypoint } from "cloudflare:workers";

export class AdminEntrypoint extends WorkerEntrypoint<Env> {
  async rebuildIndex() {
    return { ok: true };
  }
}

export class UserEntrypoint extends WorkerEntrypoint<Env> {
  async summarize(text: string) {
    return { ok: true, text };
  }
}

そして binding 側で、

{
  "services": [
    {
      "binding": "ADMIN",
      "service": "ai-core",
      "entrypoint": "AdminEntrypoint"
    }
  ]
}

こんなふうにすると、同じWorkerでも役割別に入口を分ける ことができます。

Named entrypoints for splitting responsibilities

大きめのAPIや、管理用・一般用を分けたいときにかなり便利です 😊

発展：ctx.props と ctx.exports は「上級者の入口」🧪✨

Cloudflare公式では、ctx.props を使って「特定の権限や特定の対象に限定した custom binding」を作る考え方も紹介されています。さらに ctx.exports を使うと、自分のWorkerの top-level export に対する loopback binding を自動で扱えます。 (Cloudflare Docs)

ただし、ここは第14章では 軽く知るだけでOK です。まずは、

公開APIは Hono
内部処理は Service Binding
メソッド呼び出しは RPC

この3段だけ押さえれば十分です 👍

よくあるつまずきポイント ⚠️😵‍💫

1. binding を設定したのに env に出てこない

たいていは wrangler types の再生成忘れ です。Cloudflare公式でも、binding を追加・変更したら wrangler types を再実行 するよう案内されています。 (Cloudflare Docs)

2. 内部Workerなのに公開URLへ fetch してしまう

Cloudflareのベストプラクティスでは、Worker同士の通信は 公開URLより Service Bindings が推奨です。そこをURL呼び出しに戻すと、この章の良さがかなり消えます。 (Cloudflare Docs)

3. Honoを入れたら全部解決すると思う

Honoは 外向きルーティング整理 にとても便利ですが、内部通信の設計 までは自動でやってくれません。内部構造は Service Bindings / RPC で考える、という役割分担が大事です。 (Cloudflare Docs)

4. Env型を手書きしてしまう

Cloudflare公式では、Env を手書きせず wrangler types を使う のが推奨です。手書きだと binding 名変更でズレやすいです。 (Cloudflare Docs)

Copilot活用メモ 🤝✨

GitHub Copilot は MCP で外部ツールやコンテキストをつなげられます。GitHub公式では、Copilot は IDE でも MCP を使って拡張できると案内されています。Cloudflare側も cloudflare-docs MCP server と cloudflare-observability MCP server を公開していて、Workers やログ確認に活用できます。 (GitHub Docs)

この章の学習では、たとえば Copilot にこんな感じで聞くと相性がいいです 😊

「この Service Binding 設定を確認して」
「この Hono ルートを RPC 呼び出しに分割して」
「wrangler types が必要な理由をこのコードで説明して」
「Cloudflare observability の観点で、AI Gateway のログ確認ポイントを教えて」

こういう進め方をすると、2026年らしい学び方になります 🚀

この章の演習問題 ✍️🌟

演習1

POST /api/tags を追加して、内部AI Workerに「3つのタグを返す」メソッドを生やしてみましょう。ポイントは、Hono側は入口だけ、AI処理は内部Worker側 に置くことです。

演習2

内部AI Workerに AdminEntrypoint を追加して、管理者だけが使う clearCache() や rebuildPrompts() っぽいメソッドを分けてみましょう。 named entrypoints の意味がかなりつかめます。 (Cloudflare Docs)

演習3

AI Worker の env.AI.run() に Gateway オプションを付けて、collectLog と cacheTtl を試してみましょう。「APIの形は同じなのに、中の運用だけ強くなる」体験ができます。 (Cloudflare Docs)

この章のまとめ 🎉📚

第14章の本質は、こうです。

Hono で外向きAPIを読みやすくする 🍜
Service Bindings で内部Workerを安全に呼ぶ 🔗
RPC で内部処理を関数みたいに扱う ⚡
Workers AI / AI Gateway を裏側に閉じ込めて育てやすくする 🤖

ここまで来ると、Cloudflare Workers は「小さなAPIを1本書く場所」から、「役割を分けたちゃんとしたアプリ基盤」へ見え方が変わってきます。

Final layered architecture summary

Cloudflare公式でも、複数Worker構成、type-safe RPC、AI binding、AI Gateway、Hono連携がかなりきれいにつながる形で整理されています。 (Cloudflare Docs)

必要なら次に、この第14章に続く形で 「章末課題」、「確認テスト10問」、「教材ページそのまま貼れる完成原稿」 のどれか1つに整えて渡せます。

この章のゴール 🎯📘​

この章で作る完成イメージ 🏗️✨​

まずは3つの道具をやさしく整理しよう 🧰🌈​

1. Honoって何？ 🍜​

2. Service Bindingsって何？ 🔗​

3. RPCって何？ ☎️✨​

HTTPのService BindingとRPCの違い 🆚🧠​

HTTPでつなぐ場合 🌐​

RPCでつなぐ場合 ⚡​

今回の章ではどっちを採用する？​

この章のおすすめ設計 🏛️✨​

公開API Workerの役目 🌍​

内部AI Workerの役目 🤖​

ハンズオン：公開API Worker と 内部AI Worker を分けてみよう 🛠️🤖​

手順1：内部AI Worker を作る 🤖​

ai-core / wrangler.jsonc​

ai-core / src/index.ts​

手順2：公開API Worker に Service Binding を付ける 🌍➡️🤖​

api-worker / wrangler.jsonc​

手順3：Honoで公開APIを作る 🍜✨​

api-worker / src/index.ts​

手順4：型を自動生成する 🧠🛟​

手順5：動かして確認する ▶️✨​

さらに一歩：AI Gateway を混ぜるともっと今っぽい 🚀🤖​

named entrypoints を知ると、さらに整理上手になれる 🏷️✨​

発展：ctx.props と ctx.exports は「上級者の入口」🧪✨​

よくあるつまずきポイント ⚠️😵‍💫​

1. binding を設定したのに env に出てこない​

2. 内部Workerなのに公開URLへ fetch してしまう​

3. Honoを入れたら全部解決すると思う​

4. Env型を手書きしてしまう​

Copilot活用メモ 🤝✨​

この章の演習問題 ✍️🌟​

演習1​

演習2​

演習3​

この章のまとめ 🎉📚​