1つのゲートウェイに集約する — 同期・非同期・イベントを束ねる中央APIゲートウェイ

全リクエストを単一の入口に集約し、時刻で解決して実体を呼ぶ。冪等リトライまで含めた"通る道"の設計。

WHY ONE GATEWAYなぜ入口を1つに束ねるのか

単一責務の薄いAPIを大量に積み上げていく設計では、機能単位でエンドポイントが際限なく増えていく。呼び出し側が個々の実体を直接叩く方式は一見シンプルだが、認可・リトライ・観測・レート制御といった横断的な関心事が呼び出し側ごとに散らばり、実装ごとに微妙な差異が生まれてしまう。結果として「どのAPIがどこにあり、どう呼ぶのが正しいのか」という知識が全体に分散し、運用の見通しが急速に悪化する。

中央ゲートウェイ方式は、この構造を反転させる。呼び出し側は実体の場所やバージョンを知らなくてよく、ただ「何をしたいか」だけを統一形で中央の入口へ渡す。ルーティング・認可・リトライ・計測はすべてこの一点で行われるため、方針を変えたいときも一箇所を直せば全体に効く。入口が1つに定まっていることは、後述するAIツール化(MCP / function calling)との相性の良さにも直結する。呼べる操作の一覧を機械可読に列挙し、統一形で叩かせるだけでよいからだ。

THREE ENTRYPOINTS3系統の入口 — 同期・非同期・イベント

中央ゲートウェイへの流入経路は、性質の異なる3系統に整理している。いずれも最終的には同じ中央ゲートウェイへ合流し、同じ解決・実行ロジックを通る。違いは「呼び出し元がどう待つか」だけだ。

• 同期(直接呼び出し):即時レスポンスが必要な経路。呼び出し側は結果を待ち受け、失敗はエラー応答として返る。
• 非同期(キュー経由):キューにメッセージを積み、ワーカーがゲートウェイを呼ぶ。呼び出し側は結果を待たず、バックプレッシャーとバッファをキューが吸収する。
• イベント(ストリーム消費):Kafka などのストリームを購読し、流れてくるイベントを起点に実体を呼ぶ。疎結合な波及処理に向く。

UNIFIED PAYLOAD統一ペイロードと時刻バージョニング

どの入口から来たリクエストも、ゲートウェイの内部では同一の形に正規化する。核となる項目は「呼びたい操作の名前」「宛先の論理識別子」「本体」「解決基準となる時刻」「ヘッダ」の5点だ。ゲートウェイは操作名と時刻の組を鍵にしてルート台帳を引き、その時点で有効なバージョン付き実体を選び出す。時刻を明示的に持つことで、過去日付での再現や、切り替え時刻を跨いだ挙動の検証といった「時間軸に沿った解決」が同じ経路で自然に扱える。

この分離が効くのは、呼び出し側が実体のバージョンを一切意識しなくてよくなる点だ。実体を差し替えても台帳の対応を更新するだけで済み、呼び出しコードは無変更のまま新しい実体へ流れる。

request = {
  apiName:     "order.create",     # 呼びたい操作の論理名
  appuri:      "vegas://core",      # 宛先の論理識別子
  body:        { ... },             # 本体ペイロード
  previewDate: "2026-07-03T00:00Z", # 解決基準の時刻
  headers:     { idempotencyKey: k }
}

# 名前 + 時刻 で実体(バージョン付き)を解決
target = routeTable.resolve(request.apiName, request.previewDate)
if (target == null) return error("route not found")

return gateway.invoke(target, request)

TIME-BASED RETRY冪等前提の時間ベースリトライ

失敗時のリトライは、回数ではなく時間を基準にしている。一定間隔で再試行し、開始からの経過が上限時間に達したら打ち切る。回数固定だと1回あたりの所要時間の揺らぎで実効的な粘り強さが変わってしまうが、時間基準なら「最大どれだけ待つか」を運用側が直接コントロールできる。

打ち切り時の振る舞いは入口の性質で分ける。非同期経路は打ち切ったメッセージをキューへ再投入し、後続の処理機会に委ねる。同期経路は待たせ続けられないため、その場でエラー応答を返す。いずれも再試行がある以上、同じ操作が複数回届きうる。だからこの仕組みは冪等性を前提に成り立っている。統一ペイロードに冪等キーを載せ、実体側で重複を無害化する契約がセットだ。

TRADE-OFFS一点集約のトレードオフ

入口を1つに束ねる最大の利点は、横断的関心事を一箇所で完結させられることだ。一方でその一点は、そのまま単一障害点にもボトルネックにもなりうる。ゲートウェイが詰まれば同期・非同期・イベントのすべてが同時に影響を受ける。だからこの設計では、水平スケール前提の作りと、経路ごとに適切なタイムアウトを設定する設計が事実上の必須要件になる。

• 単一障害点:多重化と迅速な切り離しで可用性を担保する。
• ボトルネック:ステートレスに保ち水平スケールできる形にする。
• タイムアウト設計:同期は短め、非同期は長めと経路ごとに調整する。

裏を返せば、ここさえ堅牢に作り込めば、その恩恵は全経路・全実体に一様に及ぶ。集約のコストは集中する一方で、集約の利益もまた一箇所への投資に集約できる、という設計判断である。