インタフェース（システム間ファイル連携）設計時の考慮事項

追記/参考情報

LGTMは0件ですがストックが多い記事です。笑

参考にしたことを知られたくない、自分の知見として報告したいという心理でしょうか？SIer系エンジニアに多そう。

システム開発の現場が少しでもよくなればいいですし、常識的な内容ですのでストックのみで構いませんが、LGTMが少ないことで記事の信頼性に疑念を持つ人もいるかなと思ったのでちょっと補足しておきます。

この記事はミッションクリティカルな業務（※1）を含んだ複数の情報システム構築・運用経験から得た知見を共有しています。
業務特性によって過不足があるでしょうし、最適解もそれぞれですので「これで完璧」とはいいませんが、ほぼほぼ考慮事項を網羅していると思います。
ぜひ設計のとっかかりやチェックリストとして活用して頂ければと思います。

（※1）例えば代表的な経験としては以下があります

• 某健康系のECサイト（年間250億円/1日1万件以上の出荷処理を処理）の倉庫管理システムのリプレース
  • サブシステムの一つにインタフェース（受注〜1万件/日〜，商品マスタ〜数10万件〜，在庫，仕入れ,...）
  • 開発と導入後の運用リーダ

方式設計

大半のシステム設計時に書いてるので、この際、まとめておく。
そのうち推奨方法・理由も記載する。

• 大方式・・・SOAP,Restful，XML-RPC FTP/SFTP､rsync､S3､etc...
• ファイル受信検知方法・・・連携されたことをどうやって検知するか？（ポーリング､S3PUTトリガ､HULFT､etc...)
• 連携の方向(IN/OUT)
• 接続許可設定
  • IP制限要否(必要な場合のIPアドレス・ポート)
  • 設定が必要な環境の洗い出し（本番､検証､...）
  • 方向（IN/OUT)
    • 受ける側だけでなく出る側でも許可設定が必要な場合があります
  • 申請から許可までに要する時間
    • 某大手企業との連携でIP許可されるまでに「10営業日」を要することがありました。
• 格納場所
  • ストレージを利用する場合は何を使う？
  • PUT/GET方法は？(SFTP？もしくはAWS Lambdaのように自動的にトリガできる？)
• ファイル名
  • どうやって一意とするか？
  • タイムスタンプをファイル名に含めるのか？その場合のフォーマットは?
  • ファイル名は同じとしてディレクトをわけるか？
• 時間・頻度
• データ量・ファイルサイズ
• 前処理
• 後処理
  • リネーム規則（タイムスタンプとか）
  • 場所移動するのか削除するのか放置か
  • 記録
  • 完了通知・エラー通知など
• 取り込み順序
  • 複数のファイルが配置されている場合､どういう順序で取り込むか?
    • 例)ファイル名の昇順で取り込む（ファイル名がファイル種別+タイムスタンプで構成されている場合）
• 取込方法
  • 洗替、追加、更新など
• 連携頻度
  • 日次?随時?その他
• 処理ログ
• エラー処理
  • リトライ要否・方法
  • エラー検知･･･最初に全部チェックするか？逐次チェックとするか？
  • エラー時処理･･･全件ロールバックになっているか？ ※一部だけ取り込むとリトライ等が複雑になるので原則として全件ロールバック
  • エラー通知・・・どうやって通知するか？誰に通知するか？
  • 空データの扱い・・・データ0件は異常か？ファイルが連携されてこない場合は異常か？
• リカバリ方法
  • 連携エラー発生時のリカバリ方法･手順を明確化する

ファイル設計

• ファイル形式・・・CSV、TSV、JSON、XML
• 文字コード・・・SJIS、UTF8
• ヘッダ有無
• 改行文字・・・CR、CRLF、LF
• 区切り文字
• 囲み文字、囲み文字のエスケープ
• データの並び・・・日時やなんらかのID順とか

各項目定義

• 項番(ファイルごとに1からの一意な連番)
  • 仕様をレビューしたり他者と情報をやり取りする際に有用です｡
• 項目名
  • 物理名
  • 論理名
• 項目の意味
• 必須かどうか
• 一意性
• データ型(数値、文字(列)、日付、時間、フラグ、...)
• 値の範囲(上限、下限、桁数)
• とりうる値と意味( たとえば 0:無効、1:有効、99:xxx)
• 値の例
• 他項目との関係
  • 例)項番nの値がXXXの場合は、この項目の値を参照して、xxxする
  • 例)項番nの値がXXXの場合は、この項目の値は｢XXX｣､それ以外の場合は､｢xxx｣となる