RESTful API が例外を処理する方法

RESTful APIの開発プロセスにおいて、例外処理は非常に重要な問題です。クライアントが API をリクエストすると、不正なリクエストパラメータ、存在しないリソース、不十分な権限など、さまざまな例外が発生する可能性があります。インターフェースの安定性と信頼性を確保するには、これらの異常な状況に効果的に対処し、対応する必要があります。この記事では、RESTful API の一般的な例外処理メソッドを紹介し、サンプルコードを提供します。

ここに画像の説明を挿入

一般的な例外の種類

RESTful API では、一般的な例外タイプには次のものがあります。

不正なリクエストパラメータ: クライアントによって送信されたリクエストパラメータは、必須パラメータの欠落、パラメータタイプの誤りなど、インターフェイス要件を満たしていません。
リソースが存在しません: 存在しないレコードのクエリ、存在しないリソースの削除など、クライアントによって要求されたリソースは存在しません。
権限が不十分です: クライアントによって要求された操作を実行するには、特定の権限またはロールが必要ですが、現在のユーザーには対応する権限またはロールがありません。
サーバーエラー: データベース接続の失敗、システム例外など、サーバー内でエラーが発生しました。

さまざまな例外タイプに対して、さまざまな処理方法を使用して、より分かりやすく明確なエラーメッセージを提供できます。

HTTPステータスコードを返す

例外を処理する場合、例外の種類に応じて対応する HTTP ステータスコードを返すことができるため、クライアントはステータスコードに応じて例外の種類を判断し、それに応じて処理できます。

一般的な HTTP ステータスコードとその意味をいくつか示します。

200 OK: リクエストは成功しました。
201 Created: リソースは正常に作成されました。
204 コンテンツがありません: リクエストは成功しましたが、応答でコンテンツが返されませんでした。
400 Bad Request: リクエストパラメータが正しくありません。
401 Unauthorized: 権限がありません。認証またはログインが必要です。
403 Forbidden: アクセスは拒否されました。現在のユーザーにはこの操作を実行する権限がありません。
404 Not Found: リソースが存在しません。
405 メソッドが許可されていません: リクエストメソッドは許可されていません。
500 内部サーバーエラー: 内部サーバーエラー。

例外が発生した場合、例外の種類に応じて対応するステータスコードを返すことができるため、クライアントはステータスコードに応じて例外の種類を判断し、それに応じて処理することができます。

エラーメッセージを返す

HTTP ステータスコードを返すだけでなく、エラーメッセージを返して、より分かりやすく明確なエラープロンプトを提供することもできます。

一般的なエラーメッセージとその意味をいくつか示します。

不正なリクエストパラメータ: エラーコードとエラーメッセージ、および特定のエラーフィールドとエラーの説明が返されます。
リソースが存在しません: エラーコードとエラー情報、およびリソースが存在しないという特定の情報を返します。
権限が不十分です: エラーコードとエラーメッセージ、および現在のユーザーの権限とロール情報が返されます。
サーバーエラー: エラーコードとエラーメッセージ、および具体的なエラーの説明と推奨される解決策が返されます。

例外が発生した場合、対応するエラーメッセージを返して、より分かりやすく明確なエラーメッセージを提供できます。

例外処理のサンプルコード

RESTful API で例外を処理する方法を示すサンプルコードを次に示します。

from flask import Flask, request, jsonify
from werkzeug.exceptions import BadRequest, NotFound, Forbidden, InternalServerError

app = Flask(__name__)

@app.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    # 查询用户信息，如果用户不存在则抛出 NotFound 异常
    user = query_user(user_id)
    if not user:
        raise NotFound('User not found')
    
    # 返回用户信息
    return jsonify(user)

@app.route('/users', methods=['POST'])
def create_user():
    # 解析请求参数，如果请求参数不正确则抛出 BadRequest 异常
    name = request.json.get('name')
    if not name:
        raise BadRequest('Name is required')
    
    # 创建用户，如果创建失败则抛出 InternalServerError 异常
    user_id = create_user(name)
    if not user_id:
        raise InternalServerError('Failed to create user')
    
    # 返回用户 ID
    return jsonify({
    
    'user_id': user_id})

@app.errorhandler(BadRequest)
def handle_bad_request(error):
    # 返回 HTTP 状态码和错误信息
    return jsonify({
    
    'code': 400, 'message': str(error)}), 400

@app.errorhandler(NotFound)
def handle_not_found(error):
    # 返回 HTTP 状态码和错误信息
    return jsonify({
    
    'code': 404, 'message': str(error)}), 404

@app.errorhandler(Forbidden)
def handle_forbidden(error):
    # 返回 HTTP 状态码和错误信息
    return jsonify({
    
    'code': 403, 'message': str(error)}), 403

@app.errorhandler(InternalServerError)
def handle_internal_server_error(error):
    # 返回 HTTP 状态码和错误信息
    return jsonify({
    
    'code': 500, 'message': str(error)}), 500

上記のサンプルコードでは、/users/<int:user_id>との2 つの API を定義しました/users。/users/<int:user_id>指定した ID のユーザー情報を照会し、/users新しいユーザーを作成するために使用されます。

このメソッドではget_user、まず指定された ID のユーザー情報を照会し、ユーザーが存在しない場合は例外をスローしますNotFound。ユーザーが存在する場合は、ユーザー情報を返します。このメソッドではcreate_user、まずリクエストパラメータを解析し、リクエストパラメータが正しくない場合は例外をスローしますBadRequest。次に、新しいユーザーの作成を試行し、作成が失敗した場合は例外をスローしますInternalServerError。最後に、新しく作成したユーザーの ID を返します。

例外処理に関しては、Flask の組み込みデコレータを使用して、、、の@app.errorhandler4 つの例外処理関数を定義します。対応する例外が発生すると、これらの関数が呼び出され、対応する HTTP ステータスコードとエラーメッセージが返されます。handle_bad_requesthandle_not_foundhandle_forbiddenhandle_internal_server_error

要約する

例外処理は、RESTful API を開発する場合に非常に重要な問題です。より分かりやすく明確なエラープロンプトを提供するには、さまざまな例外タイプに応じて、対応する HTTP ステータスコードとエラーメッセージを返す必要があります。例外処理の実装に関しては、Flask の組み込み@app.errorhandlerデコレータを使用して例外処理関数を定義し、関数内で対応する HTTP ステータスコードとエラーメッセージを返すことができます。