轉接器模式詳解與範例

意圖

把某個類別的介面轉換成用戶端所期待的另一個介面。轉接器讓原本因介面不相容而無法合作的類別能夠一起運作。它是《設計模式》（Gang of Four，簡稱 GoF）一書中七種結構型模式之一。

它解決的問題

你的商店程式碼使用一個小型的 PaymentGateway 介面：charge(amountCents, currency) 會回傳含有 ok 旗標與交易編號的結果。現在公司和一家支付服務商簽約，但它的 SDK 長得完全不同：金額是十進位字串、幣別包含在請求物件裡，而錯誤則以數字狀態碼回傳。

你無法修改這個 SDK，也不想改寫每個呼叫端去適應新的形式。如果 SDK 的風格滲透到結帳、退款與報表，日後要換服務商就會很昂貴。轉接器能把這層翻譯集中在一個類別裡。

結構與參與者

TypeScript 實作

// Target: what our code expects.
interface PaymentGateway {
  charge(amountCents: number, currency: string): { ok: boolean; id: string };
}

// Adaptee: a third-party SDK we cannot change.
class LegacyPayClient {
  makePayment(req: { amount: string; curr: string }): { status: number; ref: string } {
    return { status: req.curr === "USD" ? 200 : 422, ref: `TX-${req.amount}` };
  }
}

// Adapter: implements the Target by translating to the Adaptee.
class LegacyPayAdapter implements PaymentGateway {
  constructor(private client: LegacyPayClient) {}

  charge(amountCents: number, currency: string) {
    const res = this.client.makePayment({
      amount: (amountCents / 100).toFixed(2),
      curr: currency.toUpperCase(),
    });
    return { ok: res.status === 200, id: res.ref };
  }
}

// Client code knows nothing about LegacyPayClient.
function checkout(gateway: PaymentGateway, totalCents: number): string {
  const result = gateway.charge(totalCents, "usd");
  return result.ok ? `paid ${result.id}` : "payment failed";
}

console.log(checkout(new LegacyPayAdapter(new LegacyPayClient()), 1250)); // paid TX-12.50

日後要換成另一家服務商，只需要再寫一個轉接器。checkout 和所有其他呼叫端都不必更動，測試時也能傳入假的 PaymentGateway。

物件轉接器與類別轉接器

GoF 一書描述了兩種形式：

在 TypeScript 和 JavaScript 中，轉接一個函式往往就夠了。Node.js 內建了一個這類的小型轉接器：util.promisify() 會把回呼風格的函式轉成回傳 promise 的函式。

import { promisify } from "node:util";

// Adaptee: old callback style (error first, then result).
function readConfig(name: string, cb: (err: Error | null, value?: string) => void): void {
  setTimeout(() => cb(null, `config for ${name}`), 10);
}

// Adapted: the same function, now with a promise-based interface.
const readConfigAsync = promisify(readConfig);
console.log(await readConfigAsync("app")); // config for app

何時使用、何時不該用

在以下情況使用轉接器：

• 你想使用現有的類別，但它的介面和你的程式碼所需要的不一致。
• 你要整合第三方函式庫或舊有系統，並希望把它們的 API 限制在程式的邊緣。
• 你想讓好幾種不同的實作（例如兩家支付服務商）放在同一個介面後面。

在以下情況應避免使用：

• 兩邊都是你自己擁有的。修改其中一邊的介面通常比加一層翻譯層更簡單。
• 轉接器必須假裝支援目標介面中被轉接者其實無法真正支援的大部分功能。這會掩蓋真正的不匹配，而不是解決它。

實際應用

• Node.js：util.promisify() 把以回呼為基礎的函式轉接成 promise。
• Java：Arrays.asList() 讓陣列可以透過 List 介面使用，InputStreamReader 則讓以位元組為基礎的 InputStream 能被當成以字元為基礎的 Reader 來讀取。
• 資料庫函式庫與 ORM 會為每種資料庫各用一個轉接器或驅動程式，讓同一套查詢 API 能搭配 PostgreSQL、MySQL 或 SQLite。
• 前端程式碼也常為了同樣的理由，把瀏覽器 API 或分析 SDK 包在專案自訂的小型介面後面。

相關模式