インターフェース定義書 — 事故が最も多い文書

一言でいうと

インターフェース定義書は、説明のための文書ではなく、2つの組織が署名する合意の文書です。ここにレスポンスコードごとの対応と非機能項目が欠けていると、その空白は、障害のときにお互いの責任の押し付け合いで埋められます。

なぜこれが問題なのか

連携事故の大部分は、コードではなく合意していないことから起きます。フィールド1つの長さをお互い違うと理解していた、タイムアウトが起きたときに再送するのか照会するのかを決めていなかった、レスポンスコード9500を、一方は再試行の対象、もう一方は中止と理解していた、といったことです。

こうしたことは、開発中には表面化しません。正常なフローだけをテストするからです。そしてサービスインして最初の障害が起きたとき、定義書に書かれていない項目は、すべて「それはそちらでやっていただけるものと思っていましたが」になります。そのため、定義書はあとで誰が何をすることになっていたかを振り返れる文書でなければならず、そのためには署名が必要です。

接続が増える速さ

システム5つをお互いに直接(P2P)接続すると、接続数はいくつになるでしょうか。

N(N-1)/2
 5개 →   10
10개 →   45
20개 →  190
50개 → 1,225

このコードブロックの韓国語は、システムの個数を表す単位です。

これが、EAI(Enterprise Application Integration)という概念が生まれた理由です。真ん中にハブを置くと、接続数はNになります。各システムは、ハブとの連携だけを知っていればよいのです。

ハブが行うことは4つです。

ルーティング: この電文を誰に送るか
変換: 送信形式 → 受信形式(マッピング)
保証: 失敗時の再試行、順序、重複処理
監視: 何がいつ何件やり取りされたか

韓国の金融業界には、ここにさらに層があります。

[인터넷뱅킹 · 모바일 · ATM · 텔러]
              ↓
           MCI (Multi Channel Integration)   ← 채널 통합
              ↓
           EAI                               ← 내부 시스템 간
              ↓
[코어뱅킹 · CRM · 리스크 · 수신 · 여신]
              ↓
           FEP (Front-End Processor)         ← 대외 기관
              ↓
[금융결제원 · 카드사 · 보험사 · 신용정보원]

このコードブロックの韓国語は、上から順に、チャネル(インターネットバンキング・モバイル・ATM・テラー)、チャネルの統合を担うMCI、内部システム間を担うEAI、コアのシステム(勘定系バンキング・CRM・リスク・預金・融資)、対外機関とつなぐFEP、対外機関(金融決済院・カード会社・保険会社・信用情報院)を示しています。

MCIはチャネル側、FEPは対外側と覚えておけば、会議で迷いません。そして、この区間の相当数が、今も固定長の電文+TCPソケットです。JSONのRESTしか経験したことがない人には見慣れませんが、24時間無停止と1件あたり数msの応答が求められる区間では、今も合理的な選択です。

共通データモデル(CDM)の算数

5つのシステムがそれぞれ異なるフォーマットを使うと、マッピングはN(N-1) = 20個です(双方向)。真ん中に共通モデルを置けば、各システムは「自分のもの ↔ 共通」の2つだけを作ればよいので、N×2 = 10個です。システムを1つ追加するときのコストも、2Nではなく2になります。

これが、「標準電文」を作ろうという主張の根拠です。ただし、現実には、共通モデルを作る協議そのものがプロジェクトになります。そのため、連携対象が3つ以下なら、そのままP2Pのほうがよいという判断も正当です。数字を知って判断することと、流行を追うことは違います。

インターフェース定義書に必ず入っているべきこと

現場の格言を1つ。「インターフェース定義書にないものは、必ず違う形で実装されている」。両方の会社が違い、開発者が違い、テストの日程が違うからです。

(1) 識別情報

インターフェースID(IF-ORD-001のように体系的に)
業務名、送信システム、受信システム、担当者と連絡先
連携方式: REST / SOAP / ファイル / MQ / DBリンク / ソケット
周期: リアルタイム / 準リアルタイム(N分) / 日次バッチ(時刻を明記)

(2) 電文レイアウト

項目ごとに名前 / 型 / 長さ / 必須かどうか / サンプル値 / 備考。ここで抜けると、必ず事故になるもの:

項目	書かないと
文字セット	一方がUTF-8、一方がEUC-KRで、ハングルが文字化けします
日付フォーマット	`YYYYMMDD`、`YYYY-MM-DD`、ISO8601のどれか
金額の小数桁数	ウォン単位か、チョン単位か。丸めのルールはどうなっているか
符号の表現	負数を`-1000`で表すのか、後ろに符号を付けるのか、別の符号フィールドにするのか
NULLの表現	空文字列か、空白埋めか、文字列`NULL`か
長さを超えたとき	切り詰めるのか、エラーとするのか

ハングルの3バイト問題に特に注意する必要があります。カラムの長さ20にハングル10文字を入れようとしても、UTF-8なら30バイトなので入りません。定義書に「長さ20」としか書かれていなければ、一方は文字数で、もう一方はバイト数で実装します。「20バイト(UTF-8)」と単位まで書く必要があります。

(3) レスポンスコード体系と受信側の対応

これが最もよく抜けます。コードの一覧はあるのに、各コードに対して何をすべきかがありません。

コード	意味	受信側の対応
`0000`	正常	正常に処理します
`9001`	必須値の欠落	再試行禁止。データを修正して再送します
`9002`	認証失敗	再試行禁止。担当者に通知します
`9003`	重複リクエスト	正常とみなします(冪等)
`9500`	相手システムの一時的なエラー	再試行(バックオフ)
`9999`	不明なエラー	1回再試行したあとDLQへ

「再試行してよいエラー」と「再試行してはいけないエラー」の区別が核心です。これが定義書にないと、開発者はすべて再試行するか、すべて諦めます。前者は誤ったデータを100回送り、後者は一時的な障害で業務が止まります。

(4) 非機能項目

想定件数(日/ピーク)、最大電文サイズ
タイムアウト(接続/応答)、再試行の回数と間隔
障害時の連絡体制、復旧目標時間
保管期間(電文の原本、ログ)
個人情報を含むかどうかと、暗号化の対象項目

定義書は合意の文書です: 署名をもらいましょう

インターフェース定義書は、こちらが書く設計書ではなく、双方が署名する契約に近いものです。そのため、次の3つは必ず守ります。

バージョンと改訂履歴を文書の中に残します。「それは以前のバージョンですが」が、実際によく出てきます。
双方の担当者の確認をもらいます。メールの返信も証拠です。
変更は必ず双方の合意で行います。一方がフィールドを1つ追加すると、相手のパーサーが死ぬことがあります。特に固定長の電文は、1文字ずれるだけですべてが壊れます。

連携開発の標準的な順序

相手システムの準備ができていないという理由で開発が止まるのが、SIのよくあるリスクです。そのため、順序をこう組みます。

1. 인터페이스정의서 확정 (양쪽 서명)
2. ★ Mock 서버 구축 — 정의서대로 응답하는 가짜 상대 시스템
3. 우리 쪽 개발 + Mock 으로 단위테스트
4. 상대 시스템 준비되면 연동 테스트 (개발계)
5. 오류 케이스 테스트 ← 여기가 진짜 테스트다
6. 운영 리허설 (방화벽·인증서·계정 포함)

このコードブロックの韓国語は、開発の6つの手順を示しています。インターフェース定義書の確定(双方が署名)、Mockサーバーの構築(定義書どおりに応答する偽の相手システム)、こちら側の開発とMockでの単体テスト、相手システムの準備ができたら連携テスト(開発環境)、エラーケースのテスト(ここが本当のテスト)、本番リハーサル(ファイアウォール・証明書・アカウントを含む)です。

項目2を飛ばすと、相手の日程にこちらの日程が縛られます。そして、項目5を飛ばすプロジェクトが本当に多いです。正常ケースだけを確認してサービスインすると、最初の障害のときに再処理の手順がないことに気づきます。

項目6の括弧の中が重要です。開発環境で動いていた連携が本番環境で動かない理由は、コードではなく、ファイアウォールのポリシー、証明書、アカウントの権限の3つのうちのどれかであることがほとんどです。そして、この3つは申請から反映まで数日かかります。カットオーバー当日に発見すると、手遅れです。

現場での姿

定義書が不十分なとき、その代償は、常に遅れて、しかも他人の時間として請求されます。

フィールドの長さを、お互い違うと理解していました。こちらは16文字で切り、相手は20文字で受け取ります。正常なデータでは表面化せず、ある日、長い注文番号が入ってきて、後ろが切れたままロードされます。これはエラーではなく静かなデータ汚染なので、発見までに数週間かかります。
レスポンスコードの対応が決まっていませんでした。9500を、こちらは再試行と、相手は「中止して問い合わせ」と理解していました。障害のときに、こちらが誠実に再試行したことが、相手には爆撃として記録されます。
非機能項目がありませんでした。1秒あたり何件まで受けられるか、最大電文サイズがいくつかが書かれていないと、その限界は、サービスイン初日のトラフィックで知ることになります。

そのため、定義書のレビューで見るべきものは、文章ではなく空白です。書かれていない項目が、すなわち合意されていない項目で、合意されていない項目は、障害のときに紛争になります。