信頼性設計

背景

マルチロケーション対応の連携アプリを構築する際、システムの信頼性は非常に重要です。

標準連携では内部で処理されていたエラーハンドリングや重複防止を、独自実装では自分で設計する必要があります。「いつの間にか動かなくなっていた」という事態を防ぐため、様々な対策を実装しました。

設計上の課題

独自連携アプリでは、以下の問題に対処する必要がありました：

• 認証トークンの期限切れ - NextEngine APIのトークンには有効期限がある
• 二重処理 - Webhookの再送で同じ注文が複数回処理されるリスク
• 同時実行 - 定期処理が重複して実行されるリスク
• エラーの見落とし - 問題発生に気づかない

認証トークンの自動更新

NextEngine APIとの連携には認証トークンが必要です。このトークンには有効期限があり、期限が切れるとシステムが動かなくなります。

トークンの有効期限を常に監視し、期限切れ前に自動的に更新する仕組みを実装しました。

更新処理の詳細：

トークン管理のポイント

• 余裕を持った更新 - 有効期限の30日前から更新を試みる
• 連続更新防止 - 5分間のクールダウンで無駄なリクエストを防止
• 複数のフォールバック経路 - 更新失敗時も別の手段で対応
• アラート表示 - エラー時は管理画面にアラートを表示

処理中ロック機構

同じ処理が同時に複数実行されると、データの不整合や二重送信が発生します。分散ロックを採用してこれを防いでいます。

ロックの取得と解放

ロックの安全設計

• TTL（Time To Live）付き - 異常終了してもロックが永続しない
• 25分のTTL - 通常処理時間に余裕を持った設定
• 確実な解放 - finallyブロックでエラー時も解放

冪等性（べきとうせい）の確保

同じ処理を複数回実行しても、結果が1回実行した場合と同じになる性質を「冪等性」といいます。Webhookは再送される可能性があるため、これは非常に重要な概念です。

冪等性キーの生成

冪等性が重要な理由

• ネットワーク障害 - 送信成功したがレスポンスが届かない場合、再送が発生
• タイムアウト - 処理完了したがタイムアウトで失敗扱いになる場合
• リトライ - エラー時の自動リトライで同じリクエストが複数回届く

いずれの場合も、冪等性があれば二重処理を防げます。

ログの階層構造

用途に応じて適切なログレベルを設定しています：

ログに含まれる情報

• タイムスタンプ - ISO 8601形式で記録
• 環境名 - production/staging/development
• 処理種別 - order_sync, fulfillment_sync など
• 処理結果 - 成功/失敗、処理件数など
• エラー詳細 - エラー時はメッセージとスタックトレース

機密情報の保護

• トークンの非出力 - 認証トークンはログに出力しない
• 個人情報の除外 - 顧客の個人情報はログから除外
• プレビュー表示 - 必要な場合は先頭10文字のみ表示

データ永続化の多層構造

データの保存は複数の層で冗長化しています：

エラーリカバリーパターン

様々なエラーに対して、適切な回復処理を設計しています：

監視とアラート

問題の早期発見のため、以下の監視を行っています：

定期チェック項目

• トークン有効期限 - 30日未満で警告、7日未満でアラート
• 処理失敗率 - 一定以上の失敗が続いたら通知
• 未処理注文 - 長時間処理されない注文があれば警告

アラート通知

問題が発生した場合、管理画面にアラートを表示します。アラートには以下の情報が含まれます：

• 発生日時
• 問題の種類
• 影響範囲
• 推奨される対処法

標準連携との違い

メリット

この設計により、以下のメリットが得られました：

• 自動復旧 - 多くの問題は自動的に回復
• 可視化 - 問題発生時は即座に把握可能
• データ保全 - 二重処理やデータ欠損を防止
• 安心運用 - 「いつの間にか止まっていた」がない

運用のコツ

定期的なログ確認

問題が発生していなくても、週に1回程度はログを確認することをお勧めします。警告レベルの問題が蓄積していないか確認できます。

トークンの手動更新

自動更新が何らかの理由で失敗し続ける場合は、手動でトークンを再発行して設定することもできます。

エラー時の対応

エラーアラートが出た場合は、まずログで詳細を確認します。多くの場合、一時的な問題で自動回復していますが、継続する場合は根本原因の調査が必要です。