Grapeでの例外処理をマスターする:カスタムエラー設計、ベストプラクティス、AppSignal統合まで

Grapeは、RESTful API構築に人気のあるRubyフレームワークです。アプリケーションの安定性と信頼性を確保するうえで、例外処理は非常に重要な役割を果たします。もちろん、Grapeで構築されたAPIも例外ではありません。

本記事では、カスタム例外クラスの作成方法をはじめ、Grapeにおける例外処理の基礎を解説します。あわせて、実践的なベストプラクティスや、AppSignalを統合してエラーの監視・管理を強化する方法についてもご紹介します。

それでは始めましょう!

Grapeにおける例外処理の基本

このチュートリアルでは、Railsで構築したGrape APIにおける例外処理の方法を見ていきます。解説用として求人掲示板のデモAPIを作成しました。ソースコードはGitHubで公開していますので、ぜひご参照ください。

例外を発生させる

Grapeでは、error!を使って例外を発生させることができます。たとえば、前述の求人APIには、IDをもとに求人情報を返すshowルートがあります。レコードが存在しない場合に、次のように404エラーを返すことができます。

例外を発生させる際は、それを「独自の」方法で処理したいはずです。発生した例外をそのままユーザーに送りつけたいということは、まずないでしょう。

Rubyには、例外処理のデフォルト機構が備わっています。これは、例外が発生する可能性のあるコードをbeginブロックで囲み、発生した例外をrescueブロックで処理するという仕組みです。

典型的なシナリオでは、次のようになります。

rescue_fromメソッド

自分で意図的に発生させた場合でも、予期せず発生した場合でも、例外は適切に処理したいものです。Grapeにはデフォルトでrescue_fromメソッドが用意されており、定義済みの例外が発生したときに実行されるコードブロックを指定できます。

そこで、先ほど発生させた404エラーや、jobsリソース内で発生しうるその他の例外を捕捉(レスキュー)するために、rescue_fromメソッドを使用できます。このメソッドはjobsリソースの上に追加します。

使用するコンテンツタイプも指定できます。

しかしこの書き方は汎用的すぎます。あらゆる種類の例外を捕捉し、すべて404ステータスコード付きのエラーを返してしまうため、API利用者が400ステータスコードを期待している場合には誤解を招いてしまいます。

代わりに、処理したい例外を明示的に指定することができます。

ActiveRecord::RecordNotFoundエラーが発生した場合は、404ステータスコード付きのエラーメッセージを返します。それ以外の場合は、500ステータスコード付きのエラーメッセージを返します。

ここまでの内容でも十分改善できましたが、すべてのエラーを捕捉できるエラーハンドラが必要になったらどうすればよいのでしょうか? そこで登場するのが、例外のカスタマイズです。

Grape(Ruby)における例外のカスタマイズ

目指すのは、遭遇したエラーの種類に応じて、正しいステータスコードとともに適切なエラーメッセージを返せるエラーハンドラです。

まず、exceptions_handlerという名前のファイルを作成し、現在の例外ハンドラをこのファイルに移動します。

ExceptionHandlerモジュールではActiveSupport::Concernを使用しており、これによりincludedやclass_methodsといった機能にアクセスできます。上記のコードでは、エラーハンドラをincludedブロック内に配置しているため、このモジュールをインクルードした場所ならどこでも、定義どおりにエラーハンドラが利用可能になります。

続いて、以前エラーハンドラを置いていた箇所からコードを削除し、ExceptionsHandlerモジュールをAPIのエントリファイルであるapi.rbにインクルードします。

次に、エラー用の基底クラスを作成しましょう。このクラスは、エラーレスポンスの返却を担当します。

このクラスは、message文字列とstatusという2つのキーワード引数を受け取ります。何も渡されなかった場合は、デフォルト値が使用されます。

bodyメソッドでは、Rackレスポンスを返します。デフォルトでは、rescue_fromハンドラはRack::Responseオブジェクトを返すか、error!を呼び出すか、例外を発生させる必要があります。

それでは、ExceptionsHandler内で実際に使ってみましょう。

/errorエンドポイントを呼び出すと、レスポンスとしてoopsが返ってくることが確認できます。ここまでくれば、NotFoundエラー用のクラスも作成できます。

NotFoundクラスはmessageのみを受け付けます。BaseErrorを継承しているため、改めてRack::Responseを返す必要はありません。あとは、ExceptionsHandler内で次のように使用します。

さて、次のように手動でエラーを発生させてみます。

これは正常に動作しますが、ステータスコードは500になってしまいます。レスポンスがBaseErrorクラス内で返されるためです(BaseErrorクラスがエラーを処理するため)。

これを修正するには、ExceptionHandlerを変更して、NotFoundクラスを明示的に使ってエラーを処理するようにします。

つまり、ActiveRecord::RecordNotFoundおよびV1::Exceptions::NotFoundに対応するエラーが発生した場合にはExceptions::NotFoundを使用し、それ以外の場合はExceptions::BaseErrorを使用するようにします。

お気づきのとおり、エラークラスを増やすたびに個別のrescue_fromブロックが必要になっていきます。これはcase文を使うことでスマートに改善できます。

これで完成です!

ベストプラクティスとヒント

例外処理には数多くのベストプラクティスがありますが、ここではすぐに実践できるいくつかのヒントをご紹介します。

1. 関連する例外をグループ化する: 前述のコードで見たように、関連する例外をグループ化することで、保守性の高いコードになります。処理したい例外が増えたら、リストに追加していけばよいだけです。
2. error!のようなヘルパーを活用して、素早く例外を発生させましょう。例外処理がシンプルになります。
3. AppSignalのような例外監視ツールを積極的に活用しましょう。

AppSignal統合:Grape for Ruby

AppSignalは、アプリケーション内のエラーを監視・追跡するのに役立つツールです。Grape APIとAppSignalを統合することで、例外に関する貴重なインサイトを得られます。

このガイドでは、Grape APIとAppSignalを統合する方法を紹介します。APIでエラーが発生するたびに、以下のようにAppSignalダッシュボード上で確認できるようになります。

まとめ

例外処理は、堅牢なAPI開発において不可欠な要素です。本チュートリアルでは、Grape APIにおける例外の適切な処理方法を見てきました。また、いくつかのベストプラクティスと、Grape向けのAppSignal統合についても簡単にご紹介しました。

例外処理は継続的なプロセスです。日々の開発の中で、常に改善を重ねていくことをおすすめします。

それでは、Happy coding!

P.S. Ruby Magicの記事を公開と同時にお読みになりたい方は、Ruby Magicニュースレターを購読してください。最新記事をお見逃しなく!

P.P.S. AppSignalがActive Record統合を提供していることをご存知でしたか? 詳しくはこちらをご覧ください。

著者:Kingsley Chijioke