DO RPC 與跨物件呼叫:型別安全取代 fetch 手動路由 | Cloudflare 完整教學

// ❌ fetch 手動路由:冗長、無型別、易錯

// DO 端:要自己解析路徑、method、body
export class Counter extends DurableObject<Env> {
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    if (req.method === "POST" && url.pathname === "/increment") {
      const { amount } = await req.json<{ amount: number }>();
      const next = (await this.ctx.storage.get<number>("v") ?? 0) + amount;
      await this.ctx.storage.put("v", next);
      return Response.json({ value: next }); // 回傳也要手動包
    }
    return new Response("Not Found", { status: 404 });
  }
}

// Worker 端:要手動組 Request、再手動拆 Response
const stub = env.COUNTER.getByName("global");
const res = await stub.fetch("https://do/increment", {
  method: "POST",
  body: JSON.stringify({ amount: 5 }), // 欄位名打錯?執行期才知道
});
const { value } = await res.json<{ value: number }>(); // 型別是你手寫的,不保證對

// ✅ RPC:短、型別安全、像本地呼叫

// DO 端:就是一個公開方法
export class Counter extends DurableObject<Env> {
  async increment(amount: number): Promise<number> {
    const next = (await this.ctx.storage.get<number>("v") ?? 0) + amount;
    await this.ctx.storage.put("v", next);
    return next;
  }
}

// Worker 端:直接呼叫,TypeScript 完整推斷型別
const stub = env.COUNTER.getByName("global");
const value = await stub.increment(5); // value: number,打錯名字編譯期就報錯

export interface Env {
  // ★ 泛型參數 <Counter> 讓 stub 具備 Counter 的所有 public 方法型別
  COUNTER: DurableObjectNamespace<Counter>;
}

const stub = env.COUNTER.getByName("global");
// stub 的型別是 DurableObjectStub<Counter>
// 因此 stub.increment / stub.getCount 都有型別提示與自動完成

{
  "name": "chat-app",
  "main": "src/index.ts",
  "compatibility_date": "2024-04-03",
  "durable_objects": {
    "bindings": [
      { "name": "CHAT_ROOM", "class_name": "ChatRoom" },
      { "name": "PRESENCE", "class_name": "Presence" }
    ]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["ChatRoom", "Presence"] }
  ]
}

// src/index.ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
  PRESENCE: DurableObjectNamespace<Presence>;
}

export class ChatRoom extends DurableObject<Env> {
  private sql = this.ctx.storage.sql;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.sql.exec(`
        CREATE TABLE IF NOT EXISTS messages (
          id   INTEGER PRIMARY KEY AUTOINCREMENT,
          who  TEXT NOT NULL,
          text TEXT NOT NULL
        );
      `);
    });
  }

  // ★ RPC 方法:回傳純數字(可序列化)
  async postMessage(who: string, text: string): Promise<number> {
    const row = this.sql
      .exec<{ id: number }>(
        "INSERT INTO messages (who, text) VALUES (?, ?) RETURNING id",
        who,
        text
      )
      .one();
    return row.id;
  }

  // ★ RPC 方法:回傳純物件陣列(可序列化)
  async getRecent(limit = 20): Promise<{ who: string; text: string }[]> {
    return this.sql
      .exec<{ who: string; text: string }>(
        "SELECT who, text FROM messages ORDER BY id DESC LIMIT ?",
        limit
      )
      .toArray()
      .reverse();
  }

  // ★ 內部 private 方法「不會」被暴露為 RPC 端點
  private assertValid(text: string): void {
    if (text.length > 500) throw new Error("訊息過長");
  }
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const url = new URL(req.url);
    const room = url.searchParams.get("room") ?? "lobby";

    const stub = env.CHAT_ROOM.getByName(room);

    if (req.method === "POST") {
      const { who, text } = await req.json<{ who: string; text: string }>();
      // ★ RPC:像本地函式,回傳 Promise<number>
      const id = await stub.postMessage(who, text);
      return Response.json({ id });
    }

    // ★ RPC:回傳型別自動推斷為 { who: string; text: string }[]
    const recent = await stub.getRecent(10);
    return Response.json({ recent });
  },
} satisfies ExportedHandler<Env>;

export class ChatRoom extends DurableObject<Env> {
  // ...(前略,同上)

  async postMessage(who: string, text: string): Promise<number> {
    const row = this.sql
      .exec<{ id: number }>(
        "INSERT INTO messages (who, text) VALUES (?, ?) RETURNING id",
        who, text
      )
      .one();

    // ★ 跨物件 RPC:從 env 取得 Presence 的 stub,直接呼叫它的方法
    //   注意:這是「呼叫 B 的方法」,不是「讀 B 的變數」——兩物件不共享記憶體
    const presence = this.env.PRESENCE.getByName("global");
    await presence.markActive(who); // await 一個跨 isolate 的遠端呼叫

    return row.id;
  }
}

export class Presence extends DurableObject<Env> {
  private sql = this.ctx.storage.sql;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.sql.exec(`
        CREATE TABLE IF NOT EXISTS presence (
          who      TEXT PRIMARY KEY,
          last_ts  INTEGER NOT NULL
        );
      `);
    });
  }

  // ★ 被 ChatRoom 跨物件呼叫的 RPC 方法
  async markActive(who: string): Promise<void> {
    this.sql.exec(
      `INSERT INTO presence (who, last_ts) VALUES (?, ?)
       ON CONFLICT(who) DO UPDATE SET last_ts = excluded.last_ts;`,
      who,
      Date.now()
    );
  }

  async onlineCount(sinceMs = 60_000): Promise<number> {
    const cutoff = Date.now() - sinceMs;
    return this.sql
      .exec<{ n: number }>(
        "SELECT COUNT(*) AS n FROM presence WHERE last_ts >= ?",
        cutoff
      )
      .one().n;
  }
}

import { DurableObject, RpcTarget } from "cloudflare:workers";

// ★ 繼承 RpcTarget:此類別的實例可作為「可呼叫 stub」被回傳
class UserSession extends RpcTarget {
  constructor(private who: string, private room: ChatRoom) {
    super();
  }
  // 這些方法呼叫端可以繼續 await
  async say(text: string): Promise<number> {
    return this.room.postMessage(this.who, text);
  }
}

export class ChatRoom extends DurableObject<Env> {
  // ...(前略)

  // ★ 回傳一個 RpcTarget stub,而非純資料
  async login(who: string): Promise<UserSession> {
    return new UserSession(who, this);
  }
}

// Worker 呼叫端:拿到 session stub 後,繼續呼叫它的方法
const room = env.CHAT_ROOM.getByName("lobby");
const session = await room.login("Alice");
const msgId = await session.say("Hello!"); // 對回傳的 stub 再次 RPC

// auth-service/src/index.ts —— 被呼叫的服務 Worker
import { WorkerEntrypoint } from "cloudflare:workers";

export default class AuthService extends WorkerEntrypoint<Env> {
  // ★ public 方法即 RPC 端點
  async verifyToken(token: string): Promise<{ userId: string } | null> {
    if (token === "secret") return { userId: "u_123" };
    return null;
  }

  // WorkerEntrypoint 仍可保留傳統 HTTP 入口(可選)
  async fetch(): Promise<Response> {
    return new Response("auth-service up");
  }
}

{
  "name": "main-app",
  "services": [
    { "binding": "AUTH", "service": "auth-service", "entrypoint": "AuthService" }
  ]
}

// main-app/src/index.ts —— 呼叫端
interface Env {
  AUTH: Service<import("../auth-service/src/index").default>;
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const token = req.headers.get("authorization") ?? "";
    // ★ Service Bindings RPC:像本地呼叫另一個 Worker 的方法
    const user = await env.AUTH.verifyToken(token);
    if (!user) return new Response("Unauthorized", { status: 401 });
    return Response.json({ userId: user.userId });
  },
} satisfies ExportedHandler<Env>;

// ❌ 錯誤:User 是帶方法的 class 實例,無法 structured clone
class User { constructor(public id: string) {} greet() { return "hi"; } }
async getUser(): Promise<User> { return new User("u1"); } // 拋 DataCloneError

// ✅ 正確:回傳純物件(plain data)
async getUser(): Promise<{ id: string }> { return { id: "u1" }; }

// ✅ 或:若真要回傳「行為」,讓類別繼承 RpcTarget
class UserCtl extends RpcTarget { /* ... */ }

// ❌ 錯誤的想像:以為能直接讀另一個 DO 的欄位
const other = env.PRESENCE.getByName("global");
// other.someField ← 不存在這種用法,stub 上只有「方法」

// ✅ 正確:呼叫方法,拿回複製的資料
const count = await other.onlineCount(); // 拿到的是數字副本

// ❌ 錯誤:忘了 await,value 不是數字
const value = stub.increment(5); // value 是 Promise,不是 number

// ✅ 正確
const value = await stub.increment(5);

// DO 端:正常 throw 即可
async postMessage(who: string, text: string): Promise<number> {
  if (text.length > 500) throw new Error("訊息過長"); // 會傳回呼叫端
  // ...
}

// ✅ 呼叫端:用 try/catch 攔截遠端例外,轉成合理回應
try {
  const id = await stub.postMessage(who, text);
  return Response.json({ id });
} catch (err) {
  // 遠端 throw 的 Error 在這裡被重新拋出並捕捉
  return Response.json({ error: (err as Error).message }, { status: 400 });
}