学習・技術検証用デモ — 本システムは実際の銀行サービスではありません。

公開情報をもとに構築した教育目的のシステムです。実在する個人情報・口座情報・機密情報・認証情報等を入力しないでください。

ミニ銀行ACADEMY SYSTEM LEARNING
銀行システムをコードから学ぶ銀行デモへ
教材メニュー
学習進捗0 / 134
あと134項目
ADVANCED · 発展COURSE 07 · ENTERPRISE ARCHITECTURE

Integration Architecture：API・Event・Batchを安全に進化させる

銀行applicationは単独で完結しません。同期API、message、event、batch、fileの契約と失敗意味を設計し、旧版と新版を止めずに進化させます。

09 / 15
ENTERPRISE ARCHITECTURE · エンタープライズアーキテクチャ

Business・Application・Data・Technologyを横断し、全体最適の設計へ広げる。

先に学ぶ内容 — Prerequisite: 金融IT・信頼性

学ぶこと — LEARNING GOALS

このページで学ぶこと

  • Integration patternの選択
  • 契約・version・互換性
  • Timeout・Retry・重複・順序・照合

体験54 · INTEGRATION EVOLUTION（安全に進化させる）

Java Payment Serviceが失敗したら、自動的にlegacy経路へ切り替わるか確かめよう

まずは予想をひと言。本文を読んだ後、教材内の参照元で実際の切替設定を確認します。

体験学習 · STEP 1 / 5
  1. 01
    まず予想する — PREDICT

    まずここだけ：思ったことをひと言書く

    Java Payment Serviceが失敗したら、Next.jsは自動的に既存のlegacy経路へ切り替えてくれると思いますか？

    正解でなくて大丈夫です。「〜だと思う」から始めてみましょう。

    ヒント1を見る

    『届いたはず』を前提にした設計は、再送があると何が起きるでしょうか？

    ヒント2を見る

    自動fallbackは、本当に安全と言えるでしょうか？

    もっと詳しく：この問いで使う専門用語
    • Contractは、送受信data、意味、error、互換性、SLOの約束です。
    • Eventual Consistencyは、複数の状態が時間をかけて一致する設計です。
    • Strangler Migrationは、旧systemの周囲へ新機能を置き、範囲を段階的に移す方法です。
まずはひと言だけで大丈夫です。

この後の本文を最後まで読んでから、実際に操作して確かめるステップへ進みます。

日常語で理解する — PLAIN LANGUAGE

まず、ここだけつかむ

1

request/confirmはPAYMENT_BACKENDで選択します。未設定・空文字・legacyはNext.js→PostgREST RPC、javaはNext.js→Java Payment Service→PostgREST RPCです。不正な値はエラー、Javaのtimeout・5xx・通信断でもlegacyへ自動fallbackしません。旧OTP再発行はこの切替の対象外で、v7のRPCは常に42501で拒否します。TOTPの認可準備はNext.jsの/api/v1/transfers/mfaが担います。コードの存在は確認済みですが、本番・PreviewでJavaが選択されているかはUNKNOWNです。

2

IntegrationはAPI、event、batch、file、CDCを目的に応じて選び、contract、所有者、再送、順序、security、観測を設計します。

3

同期APIは即時結果に向き、eventは疎結合に向きますが、どちらも失敗と重複の責任を消しません。

4

更改は一括置換だけでなく、併存、shadow、段階切替、照合、切戻しを使って安全に進化させます。

順番に理解する — DIFFICULT PARTS, STEP BY STEP

難しいポイントを、順番にほどく

専門用語を覚えることより、「なぜ必要か」「このシステムのどこで使うか」を理解することが目標です。

01

Contract

やさしく言うと

送受信data、意味、error、互換性、SLOの約束です。

なぜ必要？

組織やrelease時期が違っても安全に連携するためです。

Minibankでは

Next.jsとPayment Service間のAPI request/responseを明示します。

02

Eventual Consistency

やさしく言うと

複数の状態が時間をかけて一致する設計です。

なぜ必要？

即時atomic確定が難しい分散連携を扱うためです。

Minibankでは

通知や分析projectionには使えてもLedger不変条件とは分けて考えます。

03

Strangler Migration

やさしく言うと

旧systemの周囲へ新機能を置き、範囲を段階的に移す方法です。

なぜ必要？

一括切替のriskを小さくするためです。

Minibankでは

legacy経路を残しJava経路を限定的に検証する進め方です。

発展 — ADVANCEDもっと詳しく確認する最初の学習では読まなくても問題ありません。仕組みをもっと深く理解したい場合に開いてください。

Java経路の実装と稼働確認を分ける

request/confirmはPAYMENT_BACKENDで選択します。未設定・空文字・legacyはNext.js→PostgREST RPC、javaはNext.js→Java Payment Service→PostgREST RPCです。不正な値はエラー、Javaのtimeout・5xx・通信断でもlegacyへ自動fallbackしません。旧OTP再発行はこの切替の対象外で、v7のRPCは常に42501で拒否します。TOTPの認可準備はNext.jsの/api/v1/transfers/mfaが担います。コードの存在は確認済みですが、本番・PreviewでJavaが選択されているかはUNKNOWNです。

  1. 01Next.jsがPAYMENT_BACKENDを読む
  2. 02legacy：呼出者tokenでPostgRESTへ / java：Java Payment ServiceへHTTP
  3. 03request_transfer / confirm_transfer_otpでDB処理
  4. 04Javaの@TransactionalではHTTP先のcommitを取り消せない
  5. 05応答消失時は結果不明。別backendへ自動fallbackしない

連携方式を目的で選ぶ

方式向く要求主要risk
REST / gRPC即時応答・query・command連鎖障害、timeout、coupling
Command Message非同期に特定処理を依頼重複実行、滞留
Domain Event確定事実を複数consumerへ通知順序、schema evolution、意味の乱用
Batch / File大量・締め・外部legacycutoff、再送、部分受領
CDCdata変更をstream化業務意味不足、schema coupling

契約に含めるもの

  • request / response / event schemaとsemantic
  • identity、idempotency、correlation、causation
  • time：occurred、effective、received、business date
  • error taxonomyとretryability
  • ordering・delivery guarantee・deduplication scope
  • security scope・data classification・consent
  • capacity、timeout、rate limit、backpressure
  • version、deprecation、consumer inventory

互換性を保つ移行

dual-writeは片側失敗を生むため安易に使いません。outbox、change capture、reconciliationなどで確定点を1つにします。

  1. 01Consumerと契約利用状況を可視化
  2. 02追加的なschema変更を先行
  3. 03producerが旧新を読める期間を作る
  4. 04shadow / mirrorで結果比較
  5. 05trafficを段階移行しmetricと照合を確認
  6. 06rollback可能期間を維持
  7. 07利用ゼロを証明して旧契約を廃止

Minibank Integration Review

境界契約確認
Browser→Next.jsHTTP / formauth、CSRF、二重click
Next.js→JavaPayment APIPAYMENT_BACKENDでlegacy/javaを明示選択。Java障害で自動fallbackしない。環境での選択はUNKNOWN
Java→PostgRESTRPC HTTPtoken、SQLSTATE、timeout
PostgREST→PostgreSQLfunctionsignature、GRANT、transaction
Business→LedgerDB内部event原子性、balanced journal
System→Operationsaudit / issue検知、owner、resolution

体験学習の続き · LEARNING LOOP

ここまで読めましたか？続けて確認してみましょう

ContractとStrangler Migrationの考え方を読んだところで、教材内の参照元で実際の切替設定を確認し、自分の言葉で説明してみます。

STEP 2〜5 / 5
  1. 02
    仕組みを確かめる — CONCEPT CHECK

    画面操作なしで、仕組みを確かめる

    この仕組みは、Mini Bankの画面には現れません。次のEvidenceとCode Trail、教材本文だけで理解を進めます。

  2. 03
    証拠を確認する — EVIDENCE

    何を見たか、1つずつ確かめる

    Evidence（判断の根拠となる記録）を確認したらチェックします。各項目の「何を見るか」を手がかりにしてください。

    画面を開けない項目は、Source Trail（教材の参照元）と教材の説明で確認できます。失敗を実際に起こす必要はありません。

  3. 04
    コードの処理経路を追う — CODE TRAIL

    コードを書く必要はありません

    ここでは「説明されている仕組みが、実際のMini Bankのどこに実装されているか」を確認します。まずは日本語の役割説明を読み、入力した依頼がどこへ渡るかをつかみましょう。コードの全文を読む必要はありません。

    まず経路選択の設定を見て、次にJavaへのadapterを見ます。自動fallbackがどこにも無いことを確かめましょう。

    legacy/javaを検証する設定境界。

    src/lib/config/paymentBackend.ts

    Next.jsからJavaへ渡すadapter。

    src/services/JavaPaymentBackend.ts
    教材の参照元を確認する — Source Trail ↓
  4. 05
    自分の言葉で説明する — EXPLAIN

    LEVEL 1 — やさしい説明（まずここだけ）

    なぜIntegrationの契約では『届いたはず』ではなく、idempotencyや状態照会など再送前提の設計が必要なのでしょうか？ 短い2文を目安に説明してください。

    日常語だけで完了できます。専門用語の数や正誤を自動採点するものではありません。

    ヒント1を見る

    「Contract」という言葉を使って書いてみましょう。

    ヒント2を見る

    曖昧な自動対応と、明示的なエラーのどちらが安全か考えてみましょう。

    もっと詳しく：LEVEL 2 — 専門用語を使った説明（任意）

    Contract、Eventual Consistency、Strangler Migrationの3つを使って、Integrationを安全に進化させる方法を説明してみましょう。

    挑戦する場合は、上の説明欄に追記できます。追加しなくても完了できます。

    説明の確認ポイント — Checkpoint
    • Java障害時に自動fallbackしないと説明できる
    • 再送前提の設計が必要だと説明できる
予想5文字以上・証拠2項目・説明20文字以上で完了できます。

証拠の確認：0 / 2。LEVEL 2（専門用語での説明）は任意です。

入力はこのブラウザに保存されます。Academy教材の進捗とは別の学習メモです。

理解を確かめる — CHECK YOUR UNDERSTANDING

4問で理解チェック

答えを頭の中で考えてから、各項目を開いて確認してください。

Q1eventを使えば疎結合になりますか？
答え

自動的にはなりません。schema、意味、順序、共有data、運用で強く結合する場合があります。

Q2成功応答が失われたとき何が必要ですか？
答え

idempotency、status照会、correlation、retry方針、顧客への確定状態表示が必要です。

Q3Java障害でlegacyへ自動fallbackしますか？
答え

request/confirmはPAYMENT_BACKENDで選択します。未設定・空文字・legacyはNext.js→PostgREST RPC、javaはNext.js→Java Payment Service→PostgREST RPCです。不正な値はエラー、Javaのtimeout・5xx・通信断でもlegacyへ自動fallbackしません。旧OTP再発行はこの切替の対象外で、v7のRPCは常に42501で拒否します。TOTPの認可準備はNext.jsの/api/v1/transfers/mfaが担います。コードの存在は確認済みですが、本番・PreviewでJavaが選択されているかはUNKNOWNです。

Q4安全な切替の証拠は何ですか？
答え

同一入力比較、差異分析、capacity、障害試験、切戻し試験、業務照合です。

ここまで読めましたか？

完全に暗記する必要はありません。大切な考え方を説明できそうなら押してください。

業界・外部の参照元 — INDUSTRY / EXTERNAL SOURCE

業界資料・参考文献

一般論と業界知識の根拠です。外部サイトを新しいタブで開きます。

教材の参照元 — SOURCE TRAIL

根拠と関連教材

CURRENT IMPLEMENTATIONは確認したrepository内の実装です。HISTORICAL IMPLEMENTATIONは導入・修正の履歴で、後続migrationによる再定義があり得ます。RELATED LESSONは教材への案内で、実装の一次Sourceではありません。ASSUMPTIONは仮定、UNKNOWNは未確認を表します。

確認基点: d02eae8914f39cbf06bfe422dc39c71886f82b3e / 2026-09-11。稼働環境への適用確認: UNKNOWN。パス実在の自動検査と、記述した技術的事実の確認は別です。

Implementation Status: IMPLEMENTED IN MINIBANK（この教材が扱うコードの範囲）

Runtime Verification Status: UNKNOWN（本番・Previewでの経路選択）

  • 現在の実装 — CURRENT IMPLEMENTATION — Primary Sourcesrc/lib/config/paymentBackend.tsgetPaymentBackend切替の許容値・default・不正値拒否。稼働環境の値はUNKNOWN。
  • 現在の実装 — CURRENT IMPLEMENTATION — Primary Sourcesrc/services/TransferService.tsrequestTransfer / confirmTransferOtp / reissueTransferOtprequest/confirmのみbackend切替。残存createTransfer関数のコメントは現ACLの根拠にしない。
  • 現在の実装 — CURRENT IMPLEMENTATIONsrc/services/JavaPaymentBackend.tsJavaへのHTTP adapterとエラー処理。自動fallbackなし。
  • 現在の実装 — CURRENT IMPLEMENTATIONsrc/app/api/v1/既存HTTP契約
  • 現在の実装 — CURRENT IMPLEMENTATIONservices/payment-service/src/main/java/com/minibank/payment/repository/Java→PostgREST境界
  • 過去の実装 — HISTORICAL IMPLEMENTATIONsupabase/migrations/RPC signatureとbusiness transaction