非同期処理と同期処理の適用範囲が適切か？¶
Type: Structure
Category: API・権限・セキュリティ
Audience: 設計初心者 / 設計中のチーム / レビュワー
背景・概要¶
API呼び出しにおける即時応答とバッチ/非同期処理の役割が曖昧だと、UXや信頼性、データ整合性に大きく影響する
設計段階で「即時であるべきか、非同期で良いか」の判断をすべき
例¶
- ファイルアップロード → 非同期で変換処理、結果をポーリングして完了確認
- メール送信や通知処理はタスクキューに投げる
- 同期APIでは原則リトライ不要な処理のみを受け付ける
よくある失敗例¶
- 非同期処理の完了を待ってしまい、APIタイムアウトが頻発
- バッチ処理が落ちた時にリカバリ設計がない
- 状態管理が不明瞭で、非同期処理の完了がいつか分からない
FAQ¶
Q. 非同期にしたいけど結果確認はどうすればいい？
A. ジョブIDやリソースIDを発行してGET /jobs/{id} や GET /invoices/{id} のように状態確認できるようにするか、クライアントがコールバックURLを登録して処理完了時に非同期で通知を受け取るか、UIが一定間隔で状態確認を繰り返すなどの手段を用いるとよい
Q. 同期と非同期を混ぜるのは問題ある？
A. APIの責務を明確にすればOK。イベント駆動ではドメインイベントの発行の関係でしばしば混ざる。ただし、例えば「タスクの承認依頼 → 承認処理 → 承認通知」が非同期でも、タスクのstatusは APPROVING → APPROVEDになるなどの一貫した状態遷移が行われる設計が必要