kakudooo docs

アプリケーションの特性と例外処理

前提(正当性と堅牢性の観点から)

参考: https://speakerdeck.com/twada/growing-reliable-code-phperkaigi-2022

• 安全性や正確性を重視するアプリケーション(層)
  • 突き合わせエラーに対応
• コンシューマーアプリケーション(層)
  • 単体入力エラーに対応

つまりアプリケーションや層ごとに最適な例外処理は異なり、適切なものを選択する必要がある

アプリケーションの特性とエラー表現

堅牢性の要求されるアプリケーションの例: SNS、動画視聴アプリ、ゲーム、ブラウザ、オフィスソフトなど 正当性の要求されるアプリケーションの例: 航空・宇宙、医療機器制御、自動車 ECU、通信事業者ネットワーク機器などの組み込みソフトウェアなど

とした場合に、コンシューマー向けアプリケーションの実装者としては、アプリケーションの提供先毎にどの程度の堅牢性を実現すべきかについて関心がある。

「ソフトウェアの実行を継続できるように手を尽くす」上で例外処理の結果としてのエラー表現について整理しておく。

提供先毎のアプリケーションを大きく以下の 3 つに分類してみる(もっとあるかもしれない)

• エンドユーザー向けアプリケーション
• 開発者向けアプリケーション
• 社内向けアプリケーション

今回は GraphQL API を実装する上での例外処理とエラー表現について、考えていた背景があるので、最終的なエラー表現について GraphQL を例としてあげている。

エンドユーザー向けアプリケーション

エンドユーザー向けのアプリケーションなので、操作に対する親切なフィードバックが必要である。基本的にエラーオブジェクトとしてエラーを表現する。フレームワーク(例: ActiveRecord)でメッセージが柔軟に作成される場合は、多言語ファイルで表現をユーザー向けに変換してもいいし、エラーオブジェクトを元に要件に合うエラーメッセージに変換してもよい。

エラー表現を共通化することができる場合はそれほど多くないと予想されるので、例外をグローバルレベルで補足して、エラーメッセージに変換することは最低限に留める。

GraphQL を使用している場合は Error As Schema パターンなどの使用を検討する。

開発者向けアプリケーション

API の提供先であるクライアント(サービス)が対象とするユーザー(例えば、C 向けなのか？B なのか？)による。

GraphQL を使用している場合

• C 向け: API の利用者からするとそのままエラー表現を使用できる場合が多いと想定される。→ Error As Schema の方が扱いやすい
• B 向け: API の利用者からすると別の業務エラーに変換したい場合が多いと想定される。→ 標準エラーフォーマットの方が扱いやすい

例えば

• GitHub の GraphQL API であれば、標準エラーフォーマットを使用してエラー表現を行っている
  • https://docs.github.com/ja/enterprise-server@3.12/graphql/guides/migrating-from-rest-to-graphql
• Shopify の GraphQL API だと Error As Schema を使用してエラー表現を行っている
  • https://shopify.dev/docs/api/storefront/2025-01/mutations/cartAttributesUpdate

社内向けアプリケーション

社内ユーザーなので、操作に対して次のアクションが取れるレベルのフィードバックを返せればよいことが多いと想定される。なるべく社内向けのアプリケーションにかける開発工数は減らしたいので、重要な業務に絞り親切なフィードバックを返すようにして(エンドユーザー向けアプリケーション参照)、その他はフレームワークのエラーメッセージ機能に頼る。

こちらも基本的には、例外をグローバルレベルで補足して、エラーメッセージに変換することは最低限に留める方針はそのままだが、かけられる工数が限られている場合は、グローバルレベルでエラー表現をまとめてしまう割り切り方をしてもよさそうだと考えている。 その場合は、グローバルレベルで例外を補足・変換するエラーの種類について開発者間でしっかりと共通認識を持てるようにする。

GraphQL を使用している場合は、標準エラーフォーマットパターンをメインにしつつ、必要に応じて Error As Schema パターンを補助的に使用する。