ゲートウェイ

例：単純な関数（TypeScript）

さまざまな治療プログラムを監視する架空の病院アプリケーションを考えてみましょう。これらの治療プログラムの多くは、患者が骨融合機を使用する時間を予約する必要があります。これを行うために、アプリケーションは病院の機器予約サービスと対話する必要があります。アプリケーションは、機器の利用可能な予約スロットをリストする関数を公開するライブラリを介してサービスと対話します。

equipmentBookingService.ts…

  export function listAvailableSlots(equipmentCode: string, duration: number, isEmergency: boolean) : Slot[]

アプリケーションは骨融合機のみを使用し、緊急時に使用することはないため、この関数呼び出しを簡略化するのは理にかなっています。ここでの単純なゲートウェイは、現在のアプリケーションにとって意味のある方法で名前が付けられた関数にすることができます。

boneFusionGateway.ts…

  export function listBoneFusionSlots(length: Duration) {
    return ebs.listAvailableSlots("BFSN", length.toMinutes(), false)
      .map(convertSlot)
  }

このゲートウェイ関数は、いくつかの有用なことを行っています。まず、その名前はアプリケーション内の特定の使用法に結び付けられ、多くの呼び出し元が読みやすいコードを含めることができます。

ゲートウェイ関数は、機器予約サービスの機器コードをカプセル化します。この関数のみが、骨融合機を入手するには、コード「BFSN」が必要であることを知る必要があります。

ゲートウェイ関数は、アプリケーション内で使用される型からAPIで使用される型への変換を行います。この場合、アプリケーションは、JavaScriptでのあらゆる種類の日付/時刻処理を簡略化するために、一般的で賢明な選択であるjs-jodaを使用して時間を処理します。ただし、APIは整数分の数値を使用します。ゲートウェイ関数を使用すると、呼び出し元は外部APIの規則に変換する方法を気にすることなく、アプリケーションの規則を使用できます。

アプリケーションからのすべてのリクエストは緊急ではないため、ゲートウェイは常に同じ値になるパラメーターを公開しません。

最後に、APIからの戻り値は、変換関数を使用して機器予約サービスのコンテキストから変換されます。

機器予約サービスは、次のようなスロットオブジェクトを返します。

equipmentBookingService.ts…

  export interface Slot {
    duration: number,
    equipmentCode: string,
    date: string,
    time: string,
    equipmentID: string,
    emergencyOnly: boolean,
  }

しかし、呼び出し元のアプリケーションは、次のようなスロットを持つ方が便利だと考えています。

treatmentPlanningAppointment.ts…

  export interface Slot {
    date: LocalDate,
    time: LocalTime,
    duration: Duration,
    model: EquipmentModel
  }

そのため、このコードは変換を実行します。

boneFusionGateway.ts…

  function convertSlot(slot:ebs.Slot) : Slot {
    return {
      date: LocalDate.parse(slot.date),
      time: LocalTime.parse(slot.time),
      duration: Duration.ofMinutes(slot.duration),
      model: modelFor(slot.equipmentID),
    }
  }

変換は、治療計画アプリケーションにとって意味のないフィールドを省略します。日付と時刻の文字列からjs-jodaに変換します。治療計画のユーザーは機器IDコードを気にしませんが、スロットで利用可能な機器のモデルを気にします。そのため、convertSlotは、ローカルストアから機器モデルをルックアップし、モデルレコードでスロットデータを強化します。

これを行うことで、治療計画アプリケーションは機器予約サービスの言語を処理する必要がなくなります。機器予約サービスが治療計画の世界でシームレスに機能しているふりをすることができます。

例：交換可能な接続の使用（TypeScript）

ゲートウェイは外国のコードへのパスであり、多くの場合、外国のコードは他の場所にある重要なデータへのルートです。このような外国のデータはテストを複雑にする可能性があります。治療アプリケーションの開発者がテストを実行するたびに、機器のスロットを予約したくはありません。サービスがテストインスタンスを提供する場合でも、リモート呼び出しの低速性は、高速なテストスイートの使いやすさを損なうことがよくあります。これは、テストダブルを使用するのが理にかなっている場合です。

ゲートウェイは、そのようなテストダブルを挿入する自然なポイントですが、リモートゲートウェイにはもう少し構造を持たせる価値があるため、いくつかの異なる方法があります。リモートサービスを使用する場合、ゲートウェイは2つの責任を果たします。ローカルゲートウェイと同様に、リモートサービスの語彙からホストアプリケーションの語彙への変換を行います。しかし、リモートサービスでは、リモート呼び出しがどのように行われるかの詳細など、そのリモートサービスのリモート性をカプセル化する責任もあります。2番目の責任は、リモートゲートウェイにはそれを処理するための別の要素を含める必要があることを意味します。これを接続と呼びます。

この状況では、listAvailableSlotsは構成から提供できるURLへのリモート呼び出しである可能性があります。

equipmentBookingService.ts…

  export async function listAvailableSlots(equipmentCode: string, duration: number, isEmergency: boolean) : Promise<Slot[]>
  {
    const url = new URL(config['equipmentServiceRootUrl'] + '/availableSlots')
    const params = url.searchParams;
    params.set('duration', duration.toString())
    params.set('isEmergency', isEmergency.toString())
    params.set('equipmentCode', equipmentCode)
    const response = await fetch(url)
    const data = await response.json()
    return data
  }

構成にルートURLを含めることで、異なるルートURLを提供することにより、テストインスタンスまたはスタブサービスに対してシステムをテストできます。これは素晴らしいことですが、ゲートウェイを操作することでリモート呼び出しをすべて回避できるため、テストを大幅に高速化できます。

接続は、この場合のJavaScriptのfetch APIなど、リモート呼び出しを呼び出すためのメカニズムを使用する手間も軽減します。外側のゲートウェイは、ゲートウェイのインターフェースをリモートAPIの観点からリモートシグネチャに変換する処理を行い、接続は、そのシグネチャを取得してHTTP getとして表現します。これらの2つのタスクを分離することで、それぞれがシンプルに保たれます。

次に、この接続を構築時にゲートウェイ クラスに追加します。その後、パブリック関数はこの渡された接続を使用します。

class BoneFusionGateway…

  private readonly conn: Connection
  constructor(conn:Connection) {
    this.conn = conn
  }

  async listSlots(length: Duration) : Promise<Slot[]> {
    const slots = await this.conn("BFSN", length.toMinutes(), false)
    return slots.map(convertSlot)
  }

多くの場合、ゲートウェイは同じ基盤となる接続で複数のパブリック関数をサポートします。したがって、治療アプリケーションで後で血液フィルターマシンを予約する必要がある場合、異なる機器コードで同じ接続関数を使用する別の関数をゲートウェイに追加できます。ゲートウェイは、複数の接続からのデータを単一のパブリック関数に結合することもできます。

このようなサービス呼び出しに何らかの構成が必要な場合、通常はそれを使用するコードとは別に構成するのが賢明です。治療計画のアポイントメントコードは、どのように構成すべきかを知らなくても、ゲートウェイを簡単に使用できるようにする必要があります。これを行うための簡単で便利な方法は、サービスロケーターを使用することです。

class ServiceLocator…

  boneFusionGateway: BoneFusionGateway

serviceLocator.ts…

  export let theServiceLocator: ServiceLocator

構成（通常はアプリケーションの起動時に実行されます）

  theServiceLocator.boneFusionGateway = new BoneFusionGateway(listAvailableSlots)

ゲートウェイを使用するアプリケーションコード

  const slots =  await theServiceLocator.boneFusionGateway.listSlots(Duration.ofHours(2))

この種の設定の場合、次のように接続のスタブを使用してテストを作成できます。

it('stubbing the connection', async function() {
  const input: ebs.Slot[] = [
    {duration:  120, equipmentCode: "BFSN", equipmentID: "BF-018",
     date: "2020-05-01", time: "13:00", emergencyOnly: false},
    {duration: 180, equipmentCode: "BFSN", equipmentID: "BF-018",
     date: "2020-05-02", time: "08:00", emergencyOnly: false},
    {duration: 150, equipmentCode: "BFSN", equipmentID: "BF-019",
     date: "2020-04-06", time: "10:00", emergencyOnly: false},
   
  ]
  theServiceLocator.boneFusionGateway = new BoneFusionGateway(async () => input)
  const expected: Slot[] = [
    {duration: Duration.ofHours(2), date: LocalDate.of(2020, 5,1), time: LocalTime.of(13,0),
     model: new EquipmentModel("Marrowvate D12")},
    {duration: Duration.ofHours(3), date: LocalDate.of(2020, 5,2), time: LocalTime.of(8,0),
     model: new EquipmentModel("Marrowvate D12")},
  ]
  expect(await suitableSlots()).toStrictEqual(expected)
});

このようにスタブを作成すると、リモート呼び出しをまったく行わずにテストを作成できます。

ただし、ゲートウェイが行う変換の複雑さによっては、リモートサービスの言語ではなく、アプリケーションの言語でテストデータを記述したい場合があります。suitableSlotsが間違った種類の機器モデルのスロットを削除することを確認するこのようなテストでそれができます。

it('stubbing the gateway', async function() {
  const stubGateway = new StubBoneFusionGateway()
  theServiceLocator.boneFusionGateway = stubGateway
  stubGateway.listSlotsData = [
    {duration: Duration.ofHours(2), date: LocalDate.of(2020, 5,1), time: LocalTime.of(12,0),
     model: new EquipmentModel("Marrowvate D10")}, // not suitable
    {duration: Duration.ofHours(2), date: LocalDate.of(2020, 5,1), time: LocalTime.of(13,0),
     model: new EquipmentModel("Marrowvate D12")},
    {duration: Duration.ofHours(3), date: LocalDate.of(2020, 5,2), time: LocalTime.of(8,0),
     model: new EquipmentModel("Marrowvate D12")},
  ]
  const expected: Slot[] = [
    {duration: Duration.ofHours(2), date: LocalDate.of(2020, 5,1), time: LocalTime.of(13,0),
     model: new EquipmentModel("Marrowvate D12")},
    {duration: Duration.ofHours(3), date: LocalDate.of(2020, 5,2), time: LocalTime.of(8,0),
     model: new EquipmentModel("Marrowvate D12")},
  ]
  expect(await suitableSlots()).toStrictEqual(expected)   
});

class StubBoneFusionGateway extends BoneFusionGateway {  
  listSlotsData: Slot[] = []

  async listSlots(length: Duration) : Promise<Slot[]> {
    return this.listSlotsData
  }
  
  constructor() {
    super (async () => []) //connection not used, but needed for type check
  }
}

ゲートウェイをスタブ化すると、suitableSlots内のアプリケーションロジックが何をすべきかが明確になります。この場合は、Marrowvate D10をフィルタリングします。しかし、これを行う場合、ゲートウェイ内の変換ロジックをテストしていないため、少なくとも接続レベルでスタブするいくつかのテストが必要です。また、リモートシステムのデータがそれほど理解しにくいものでなければ、接続のみをスタブするだけで済むかもしれません。ただし、作成するテストに応じて、両方のポイントでスタブできると便利なことがよくあります。

私のプログラミングプラットフォームでは、リモート呼び出しを直接スタブする何らかの形式がサポートされている場合があります。たとえば、JavaScriptのテスト環境であるJestでは、モック関数を使用してあらゆる種類の関数呼び出しをスタブできます。利用できるものは使用しているプラットフォームによって異なりますが、ご覧のとおり、追加のツールなしでこれらのフックを備えるようにゲートウェイを設計することは難しくありません。

このようなリモートサービスをスタブ化する場合、リモートサービスに関する私の仮定が、そのサービスが行う変更と同期していることを確認するために、コントラクトテストを使用するのが賢明です。

例：YouTubeにアクセスするコードをリファクタリングしてゲートウェイを導入する（Ruby）

数年前、記事を書き、YouTubeのAPIにアクセスして動画に関する情報を表示するコードをいくつか示しました。コードがどのように異なる懸念事項を絡み合わせているかを示し、それらを明確に分離するためにコードをリファクタリングします。その過程でゲートウェイを導入します。既存のコードベースにゲートウェイを導入する方法を段階的に説明します。