Flask エラーハンドリング

Flask は柔軟なエラーハンドリングの仕組みを提供し、アプリケーション内のさまざまなエラーをキャッチして処理できます。

優れたエラーハンドリングは「バグを出さない」ことだけでなく、バグが発生したときにユーザーに親しみやすい体験を提供することでもあります。

この章では、Flask でエラーページをカスタマイズし、ログを管理する方法を紹介します。


カスタムエラーページ

デフォルトでは、Flask は 404 などのエラーに対して、黒地に白文字のシンプルなページを表示します。

使用する@app.errorhandler@app.errorhandler デコレータを使用すると、特定の HTTP ステータスコードに合わせてエラーページをカスタマイズできます:

例

from flask import Flask, render_template

app = Flask(__name__)

# 404 エラーを処理——ページが見つかりません
@app.errorhandler(404)
def page_not_found(error):
    # 注意:ステータスコード 404 を明示的に返す必要があります
    return render_template("404.html"), 404

# 500 エラーを処理——サーバー内部エラー
@app.errorhandler(500)
def internal_error(error):
    return render_template("500.html"), 500

# 403 エラーを処理——アクセス禁止
@app.errorhandler(403)
def forbidden(error):
    return render_template("403.html"), 403

対応する 404 テンプレート:

例

<!-- ファイルパス: templates/404.html -->
<!DOCTYPE html>
<html>
<head>
    <title>404 - ページが存在しません</title>
    <style>
        body { text-align: center; padding-top: 60px; font-family: Arial; }
        h1 { font-size: 72px; color: #e74c3c; margin: 0; }
        p { color: #666; font-size: 18px; }
        a { color: #3498db; }
    </style>
</head>
<body>
    <h1>404</h1>
    <p>申し訳ございません。お探しのページは存在しません。</p>
    <p><a href="/">ホームページに戻る</a></p>
</body>
</html>

にerrorhandlerデコレータを付けた関数内では、returnステータスコードを明示的に指定する必要があります。指定しない場合、, 404Flask はデフォルトで 200 ステータスコードを返すため、ブラウザや検索エンジンはこれをエラーページとは見なしません。


例外クラスの登録

ステータスコードに加えて、@app.errorhandler例外クラスを直接登録することもできます:

例

from werkzeug.exceptions import HTTPException

@app.errorhandler(HTTPException)
def handle_http_exception(error):
    「400, 401, 403, 404 などのすべての HTTP 例外を一元のに処理」
    return f"""
<h1>HTTP エラー {error.code}</h1>
    <p>{error.description}</p>
<p><a href="/">サンプル ホームページに戻る</a></p>
    """
, error.code

abort を使用したエラーの発生

ビュー関数内では、abort()abort を使用して HTTP エラーを明示的に発生させます:

例

from flask import abort

# 記事データベースを模擬する
articles = {
    1: {"title": "Flask 入門チュートリアル"},
    2: {"title": "Python 基礎"},
}

@app.get("/article/<int:article_id>")
def view_article(article_id):
    article = articles.get(article_id)

    if article is None:
        # 記事が存在しないため、404 を返す
        # description パラメータは errorhandler に渡されます
        abort(404, description=f「記事ID {article_id} は存在しません」)

    return f"<h1>{article['title']}</h1>"

@app.get("/admin")
def admin_panel():
    # admin 権限のないユーザーが管理画面にアクセスした場合
    abort(403, description="管理者権限がありません")

ログ記録

Flask は Python 標準ライブラリのlogginglogging モジュールを使用し、app.logger をapp.logger通じてログを記録できます。

ログは問題の調査に極めて重要です。単に print を使うだけでは不十分でprint()、ログはより豊かなコンテキストとより優れた制御力を提供します。

例

from flask import Flask, request

app = Flask(__name__)

@app.route("/")
def index():
    # さまざまなレベルのログ
    app.logger.debug("ホームページにアクセス")                    # デバッグ情報。本番環境では通常出力されません
    app.logger.info("ユーザーの IP: %s", request.remote_addr)  # 一般的な情報
    app.logger.warning("異常なアクセスパターンを検出しました")         # 警告:注意が必要だが実行には影響しない
    app.logger.error("データベース接続が失敗しました")               # エラー:機能に影響がある
    app.logger.critical("ディスク容量が不足しているため、サービスをまもなく停止します")  # 重大なエラー:サービスが停止する可能性があります
    return "OK"

ログレベル(低いものから高いものへ):

レベル 使用シーン
DEBUG 開発・デバッグ時の詳細情報。本番環境ではデフォルトで出力されません
INFO 一般的な実行情報。リクエスト記録やサービス起動など
WARNING 警告情報。潜在的な問題だが現在の実行には影響しない
ERROR エラー情報。一部の機能でエラーが発生したが、サービスは稼働中
CRITICAL 重大なエラー。サービスが停止する可能性がある

Debug モードでは、Flask のログレベルは自動的にDEBUGDEBUG に設定されます。本番環境では必要に応じてINFO 或 WARNINGWARNING に設定し、不要な情報を大量に出力しないようにします。


ログ出力の設定

ログをファイルに書き込むと、事後の分析や調査に便利です:

例

import logging
from logging.handlers import RotatingFileHandler

# ファイルログハンドラーを設定——ログファイルが 10MB に達すると自動でローテーション
handler = RotatingFileHandler(
    "サンプル_app.log",     # ログファイルのパス
    maxBytes=10 * 1024 * 1024,  # 単一ファイルの最大サイズ 10MB
    backupCount=5          # 最新のバックアップ 5 つを保持
)

# ログ形式を設定
handler.setFormatter(logging.Formatter(
    "[%(asctime)s] %(levelname)s in %(module)s: %(message)s"
))

# handler を Flask の logger に追加
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)

未処理の例外の捕捉

app.errorhandler(500) を使用すると、app.errorhandler(500)未処理の例外をキャッチしてログを記録できます:

例

import traceback

@app.errorhandler(500)
def internal_error(error):
    # 完全な例外スタックを記録
    app.logger.error("サーバー内部エラー:\n%s", traceback.format_exc())

    # ユーザーに親しみやすいエラーページを表示
    return """
<h1>500 - サーバー内部エラー</h1>
<p>申し訳ございません。サーバーで予期しないエラーが発生しました。この問題は記録いたしました。しばらくしてからもう一度お試しください。</p>
<p>この問題が続く場合は、サンプル テクニカルサポートまでお問い合わせください。</p>
    """
, 500

一般的な HTTP エラーコード早見表

ステータスコード 意味 一般的な原因
400 Bad Request リクエストパラメータの形式が正しくない、必須フィールドが不足している
401 Unauthorized ユーザーが未ログイン、または認証に失敗した
403 Forbidden ユーザーはログイン済みだがアクセス権限がない
404 Not Found リソース(記事、ユーザーなど)が存在しない
405 Method Not Allowed 誤った HTTP メソッドを使用した(例:GET で POST インターフェースにアクセス)
500 Internal Server Error コードの例外、データベース接続失敗などの未処理のエラー
その他の拡張