Flask入门教程(十五):错误处理与日志——打造健壮的Web应用

1. 自定义错误页面

默认情况下,Flask对404等错误会显示简单的黑底白字页面。使用@app.errorhandler装饰器可以为特定HTTP状态码定制错误页面:

复制代码
from flask import Flask, render_template

app = Flask(__name__)

# 处理404错误——页面未找到
@app.errorhandler(404)
def page_not_found(error):
    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

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必须显式带上状态码 。如果不写, 404,Flask会默认返回200状态码,浏览器和搜索引擎不会认为这是一个错误页面。

2. 异常类注册

除了状态码,@app.errorhandler还可以直接注册异常类:

复制代码
from werkzeug.exceptions import HTTPException

@app.errorhandler(HTTPException)
def handle_http_exception(error):
    """统一处理所有HTTP异常(如400, 401, 403, 404等)"""
    return f"""
    <h1>HTTP 错误 {error.code}</h1>
    <p>{error.description}</p>
    <p><a href="/">返回 RUNOOB 首页</a></p>
    """, error.code

# 也可以注册自定义异常类
class CustomError(Exception):
    pass

@app.errorhandler(CustomError)
def handle_custom_error(error):
    return "自定义错误发生了", 400

3. 使用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
        abort(404, description=f"文章 ID {article_id} 不存在")
    
    return f"<h1>{article['title']}</h1>"

@app.get("/admin")
def admin_panel():
    # 没有权限访问管理后台
    abort(403, description="你没有管理员权限")

abort()的description参数会被传递给errorhandler,可以在自定义错误页面中显示详细信息。

4. 日志记录

Flask使用Python标准库的logging模块,通过app.logger即可记录日志。日志对于排查问题至关重要------不要只用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的日志级别自动设为DEBUG。生产环境中应按需设置为INFO或WARNING,避免输出太多无用信息。

5. 配置日志输出到文件

将日志写入文件,便于事后分析和排查:

复制代码
import logging
from logging.handlers import RotatingFileHandler

# 配置文件日志处理器——日志文件达到10MB后自动轮转
handler = RotatingFileHandler(
    "runoob_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)

日志格式常用占位符

占位符 说明
%(asctime)s 时间戳
%(levelname)s 日志级别(INFO、ERROR等)
%(module)s 模块名
%(funcName)s 函数名
%(lineno)d 行号
%(message)s 日志消息

6. 捕获未处理的异常

使用@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

7. 蓝图中的错误处理

蓝图也支持独立的错误处理器,只作用于该蓝图的路由:

复制代码
# auth.py
from flask import Blueprint, render_template

bp = Blueprint("auth", __name__)

@bp.errorhandler(404)
def auth_not_found(error):
    """auth蓝图专用的404错误页面"""
    return render_template("auth/404.html"), 404
注册方式 作用范围
@app.errorhandler 全局生效
@bp.errorhandler 仅在该蓝图路由中生效

8. 常见HTTP错误码速查

状态码 含义 常见原因
400 Bad Request 请求参数格式错误、缺少必要字段
401 Unauthorized 用户未登录或认证失败
403 Forbidden 用户已登录但没有访问权限
404 Not Found 资源(文章、用户等)不存在
405 Method Not Allowed 使用了错误的HTTP方法
429 Too Many Requests 请求频率超过限制
500 Internal Server Error 代码异常、数据库连接失败等未处理错误
502 Bad Gateway 代理服务器收到无效响应
503 Service Unavailable 服务暂时不可用

9. 错误处理最佳实践

实践 说明
✅ 自定义错误页面 使用@app.errorhandler覆盖默认错误页面,保持品牌一致性
✅ 记录错误日志 在errorhandler中记录traceback,便于排查问题
✅ 区分客户端错误(4xx)和服务器错误(5xx) 前者返回提示信息,后者记录完整堆栈
✅ 使用环境变量控制日志级别 开发环境用DEBUG,生产环境用INFO或WARNING
✅ 敏感信息脱敏 错误日志中不要记录密码、Token等敏感信息
❌ 在生产环境暴露堆栈 不要向用户显示完整的异常堆栈
❌ 忽略错误 每个abort()和可能抛异常的地方都应有对应的处理

小结

本章全面讲解了Flask的错误处理与日志机制。@app.errorhandler装饰器可自定义各类HTTP错误页面,支持状态码和异常类两种注册方式;视图函数中使用abort()主动触发错误并传递描述信息;日志通过app.logger记录,支持DEBUG到CRITICAL五个级别,可配合RotatingFileHandler实现日志文件的自动轮转;traceback.format_exc()可捕获异常堆栈;蓝图也支持独立的错误处理器。完善的错误处理加上规范的日志记录,是打造健壮可靠Web应用的必备手段。

相关推荐
澹锦汐3 小时前
纯前端秋日银杏与枫叶落叶色板智能聚类器:基于 K-Means 色彩量化与直方图自动配方提取
前端·人工智能·ai·语言模型·vue·react·k-means
qq_158895411114 小时前
Suno-API 是什么?官方 V6 模型与 Python / TypeScript 接入指南
python·ai音乐·suno api
Flynt11 小时前
AI 写的 Three.js 大屏,为什么越跑越卡?我在 Node 里复现了它的内存曲线
前端·ai编程·three.js
一个游离的指针13 小时前
Vue2:vue-router
前端·javascript·vue.js
学无止境小袁同学14 小时前
Google ADK 学习指南
python·llm·agent·多agent·google adk·llmagent·agent cli
郝学胜-神的一滴15 小时前
Effective Python 条款35:用类封装替代生成器异常注入
开发语言·人工智能·python·金融·pandas·scikit-learn·matplotlib
火山引擎和TA的超级拍档们15 小时前
产品情报局 11 | AI 数据湖 LAS:打造大模型时代多模态数据底座
前端·后端
JavaGuide15 小时前
Gemini 真的变强了,写代码做视频的能力接近 Claude Opus5.5 了!
前端·ai编程
niceyayale15 小时前
WebRTC 延迟怎么调试:从 ICE 到 jitter buffer 的六个观测点
前端