FastAPIのカスタム例外ハンドリング

FastAPIとカスタム例外の概要

FastAPIは、Pythonの非常に高速な（高性能）、使いやすい、モダンな、高速（高性能）なWebフレームワークで、APIの作成に特化しています。FastAPIは、Python 3.6以降の型ヒントを使用してAPIパラメータの型を宣言します。

例外ハンドリングは、FastAPIアプリケーションの重要な部分です。例外は、プログラムが期待する通りに動作しない場合に発生します。例外を適切にハンドリングすることで、エラーが発生したときでもユーザーに適切なレスポンスを返すことができます。

FastAPIでは、HTTPExceptionという組み込みの例外クラスを提供しています。このクラスを使用すると、HTTPステータスコードとエラーメッセージを含む例外を簡単に発生させることができます。

しかし、場合によっては、特定のエラー条件に対してカスタムの例外クラスを作成したいと思うかもしれません。FastAPIでは、Pythonの標準的な例外クラスを継承してカスタム例外を作成することができます。そして、そのカスタム例外を@app.exception_handler()デコレータを使用してハンドルすることができます。

この記事では、FastAPIでのカスタム例外の作成とハンドリングについて詳しく説明します。具体的なコード例とその説明を提供することで、読者が理解を深めることができます。

FastAPIのHTTPExceptionの使用方法

FastAPIでは、HTTPExceptionという組み込みの例外クラスを提供しています。このクラスを使用すると、HTTPステータスコードとエラーメッセージを含む例外を簡単に発生させることができます。

以下に、HTTPExceptionの基本的な使用方法を示します。

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    items = {"item1": "This is item 1", "item2": "This is item 2"}
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

上記のコードでは、/items/{item_id}へのGETリクエストを処理するルートを定義しています。リクエストされたitem_idがitemsディクショナリに存在しない場合、HTTPExceptionを発生させています。この例外は、ステータスコード404（Not Found）と詳細メッセージ"Item not found"を持っています。

FastAPIは、発生したHTTPExceptionを自動的に捕捉し、そのステータスコードと詳細を含むJSONレスポンスを生成します。これにより、APIのエラーハンドリングを簡単に行うことができます。

次のセクションでは、これをさらに拡張して、カスタム例外を作成し、それをどのようにハンドリングするかについて説明します。

カスタム例外の作成と発生

FastAPIでは、Pythonの標準的な例外クラスを継承してカスタム例外を作成することができます。以下に、カスタム例外の作成とその発生方法を示します。

from fastapi import FastAPI, HTTPException

class CustomException(HTTPException):
    def __init__(self, status_code, detail):
        super().__init__(status_code=status_code, detail=detail)

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    items = {"item1": "This is item 1", "item2": "This is item 2"}
    if item_id not in items:
        raise CustomException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

上記のコードでは、CustomExceptionという新しい例外クラスを作成しています。このクラスはHTTPExceptionを継承しており、コンストラクタでステータスコードと詳細メッセージを受け取ります。

そして、/items/{item_id}へのGETリクエストを処理するルート内で、リクエストされたitem_idがitemsディクショナリに存在しない場合、このCustomExceptionを発生させています。

FastAPIは、発生したCustomExceptionを自動的に捕捉し、そのステータスコードと詳細を含むJSONレスポンスを生成します。これにより、APIのエラーハンドリングをより柔軟に行うことができます。

次のセクションでは、エラーレスポンスのカスタマイズについて説明します。

エラーレスポンスのカスタマイズ

FastAPIでは、エラーレスポンスの形式をカスタマイズすることができます。これにより、エラー情報をより詳細に、または特定の形式でユーザーに提供することが可能になります。

以下に、エラーレスポンスのカスタマイズ方法を示します。

from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse

class CustomException(HTTPException):
    def __init__(self, status_code, detail, headers=None):
        super().__init__(status_code=status_code, detail=detail, headers=headers)
        self.headers = headers

@app.exception_handler(CustomException)
async def custom_exception_handler(request, exc: CustomException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": f"Oops! {exc.detail} occurred."},
        headers=exc.headers,
    )

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    items = {"item1": "This is item 1", "item2": "This is item 2"}
    if item_id not in items:
        raise CustomException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

上記のコードでは、CustomExceptionクラスを作成し、その例外をハンドリングするためのカスタム例外ハンドラを定義しています。この例外ハンドラは、@app.exception_handler()デコレータを使用して登録され、CustomExceptionが発生したときに呼び出されます。

例外ハンドラ内では、JSONResponseを使用してカスタムのエラーレスポンスを作成しています。このレスポンスには、ステータスコード、カスタムメッセージ、および任意のヘッダーが含まれます。

このように、FastAPIではエラーレスポンスのカスタマイズが可能で、APIのエラーハンドリングをより柔軟に行うことができます。

次のセクションでは、カスタムヘッダーの追加について説明します。

カスタムヘッダーの追加

FastAPIでは、エラーレスポンスにカスタムヘッダーを追加することができます。これにより、エラー情報をより詳細に、または特定の形式でユーザーに提供することが可能になります。

以下に、カスタムヘッダーの追加方法を示します。

from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse

class CustomException(HTTPException):
    def __init__(self, status_code, detail, headers=None):
        super().__init__(status_code=status_code, detail=detail, headers=headers)
        self.headers = headers

@app.exception_handler(CustomException)
async def custom_exception_handler(request, exc: CustomException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": f"Oops! {exc.detail} occurred."},
        headers=exc.headers,
    )

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    items = {"item1": "This is item 1", "item2": "This is item 2"}
    if item_id not in items:
        raise CustomException(status_code=404, detail="Item not found", headers={"X-Error": "Item not found"})
    return {"item": items[item_id]}

上記のコードでは、CustomExceptionを発生させる際に、headers引数を使用してカスタムヘッダーを追加しています。この例では、"X-Error": "Item not found"というカスタムヘッダーを追加しています。

FastAPIは、発生したCustomExceptionを自動的に捕捉し、そのステータスコード、詳細、およびカスタムヘッダーを含むJSONレスポンスを生成します。これにより、APIのエラーハンドリングをより柔軟に行うことができます。

次のセクションでは、カスタム例外ハンドラの作成と使用について説明します。

カスタム例外ハンドラの作成と使用

FastAPIでは、カスタム例外ハンドラを作成して、特定の例外が発生したときの動作をカスタマイズすることができます。以下に、カスタム例外ハンドラの作成と使用方法を示します。

from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse

class CustomException(HTTPException):
    def __init__(self, status_code, detail, headers=None):
        super().__init__(status_code=status_code, detail=detail, headers=headers)
        self.headers = headers

@app.exception_handler(CustomException)
async def custom_exception_handler(request, exc: CustomException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": f"Oops! {exc.detail} occurred."},
        headers=exc.headers,
    )

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    items = {"item1": "This is item 1", "item2": "This is item 2"}
    if item_id not in items:
        raise CustomException(status_code=404, detail="Item not found", headers={"X-Error": "Item not found"})
    return {"item": items[item_id]}

上記のコードでは、@app.exception_handler()デコレータを使用してカスタム例外ハンドラを登録しています。このデコレータは、引数として例外クラス（この場合はCustomException）を取り、その例外が発生したときに呼び出される関数を指定します。

例外ハンドラの関数（この場合はcustom_exception_handler）は、リクエストオブジェクトと例外オブジェクトを引数に取り、レスポンスオブジェクトを返します。この関数内で、例外の詳細を使用してカスタムのエラーレスポンスを作成しています。

このように、FastAPIではカスタム例外ハンドラを作成することで、特定の例外が発生したときの動作をカスタマイズすることができます。これにより、APIのエラーハンドリングをより柔軟に行うことができます。次のセクションでは、さらに詳しく説明します。