应使用@app.errorhandler(exception)全局捕获未处理异常并返回jsonify()响应，开发时记录完整堆栈到日志、响应仅返回泛化消息，生产环境禁用traceback暴露；推荐定义带status_code和error_code的自定义异常类实现结构化错误处理。
Flask 中如何全局捕获未处理异常并转为 JSON 响应
默认情况下，Flask 在开发模式下会返回 HTML 错误页面，生产环境遇到未捕获异常直接 500 崩溃——这和 API 接口要的 {"error": "..."} 完全不匹配。必须主动拦截异常流，重写响应体。
核心是使用 app.register_error_handler() 或 @app.errorhandler() 绑定异常类，再手动构造 jsonify() 响应。注意：它只捕获被 Flask 框架“感知到”的异常（比如视图函数抛出的、或中间件未吞掉的），不包括后台线程、信号处理或 sys.excepthook 范围内的错误。
- 对所有
Exception注册 handler 是最粗粒度做法，但会掩盖 404/405 等标准 HTTP 异常，建议优先捕获具体子类（如ValueError、KeyError） - 务必设置响应状态码，否则默认是 200；常见做法是将非 HTTP 异常映射为
500，自定义业务异常映射为400或422 - 不要在 handler 里再抛异常，否则会触发默认 500 页面（尤其在调试模式下）
怎样定义和抛出自定义异常类以便统一 JSON 化
硬编码 raise Exception("xxx") 无法携带状态码和错误码字段。推荐定义继承 Exception 的子类，并附加 status_code 和 error_code 属性，让 error handler 能提取结构化信息。
示例：
class ApiError(Exception):
def __init__(self, message, status_code=400, error_code=None):
super().__init__(message)
self.message = message
self.status_code = status_code
self.error_code = error_code or "GENERIC_ERROR"
<h1>视图中使用</h1><p>@app.route('/user/<user_id>')
def get_user(user_id):
if user_id </user_id></p>
- 在 error handler 中通过
isinstance(e, ApiError)判断并提取字段，比用字符串匹配更可靠 - 避免把敏感信息（如数据库路径、堆栈）直接返回给客户端，
ApiError构造时就该做脱敏 - 如果项目已有多个模块，建议把
ApiError放在公共包（如app/errors.py）中供复用
为什么 @app.errorhandler(500) 不捕获所有异常
@app.errorhandler(500) 只响应最终被 Flask 认定为“HTTP 500 内部服务器错误”的场景，而很多异常在到达它之前就被更早的 handler 截获了——比如 @app.errorhandler(Exception) 会先于 500 执行，一旦它返回了响应，就不会再走 500 流程。
- 注册顺序无关紧要，匹配优先级由异常类型决定：越具体的类（如
ValueError）越先触发，Exception是兜底 -
@app.errorhandler(500)实际上等价于@app.errorhandler(InternalServerError)，它只捕获明确被设为 500 的响应，不是所有未捕获异常 - 调试时可在 handler 里加
print(type(e).__name__)确认实际抛出的是什么类型，避免误以为“没生效”
如何确保 JSON 异常响应在所有环境（含调试模式）下一致
Flask 的 DEBUG=True 会强制启用 Werkzeug 调试器，覆盖你写的 errorhandler，导致开发时看到 HTML 堆栈而不是 JSON。这不是 bug，是设计使然——但 API 开发者通常希望即使在 debug 模式下也保持 JSON 格式，便于前端联调。
- 方案一：改用
app.config['PROPAGATE_EXCEPTIONS'] = True并配合app.before_first_request动态关闭调试器（不推荐，破坏调试体验） - 方案二（推荐）：在启动时判断环境，仅在
DEBUG=False时启用 JSON handler；开发阶段靠日志 + Postman 查看原始异常，而非依赖响应体 - 方案三：用 WSGI 中间件（如
ProxyFix后加一层异常捕获）统一处理，但增加了部署复杂度
真正容易被忽略的是：异常对象的 __dict__ 可能包含不可 JSON 序列化的字段（比如 request 对象），直接 jsonify(e.__dict__) 会报 TypeError。所有序列化操作必须显式控制字段，只取字符串、数字、字典、列表这几类安全类型。
