怎么统一处理异常、统一返回 JSON 格式？

目标：所有接口返回统一结构 `{"code": 0, "data": ..., "msg": "ok"}`，错误时也是同一结构，前端一套解析逻辑，不用为每个接口单独处理报错。

第 1 步：定义统一响应辅助函数

# utils.py
def success(data=None, msg="ok"):
    return {"code": 0, "data": data, "msg": msg}

def fail(msg="error", code=1, data=None):
    return {"code": code, "data": data, "msg": msg}

第 2 步：业务接口按统一结构返回

from utils import success, fail

@app.get("/api/user/<int:uid>")
def get_user(uid):
    user = find_user(uid)              # 业务查询
    if user is None:
        return fail("用户不存在", code=404), 404
    return success(user)

第 3 步：统一处理 HTTP 错误（404/405/413...）

@app.errorhandler(404)
def not_found(e):
    return fail("接口不存在", code=404), 404

@app.errorhandler(405)
def method_not_allowed(e):
    return fail("方法不允许", code=405), 405

@app.errorhandler(413)
def too_large(e):
    return fail("文件太大", code=413), 413

第 4 步：兜底捕获所有未处理异常（关键）

import logging
logging.basicConfig(level=logging.ERROR)

@app.errorhandler(Exception)
def handle_exception(e):
    # 一定要记日志，否则异常被吞掉没法排查
    logging.exception("未捕获异常: %s", e)
    # 生产环境不要把内部错误信息返回给用户，防信息泄露
    return fail("服务器内部错误", code=500), 500

配套注意事项：

1. 请求体校验失败也统一返回：写一个装饰器或在视图里 try: data = request.get_json() except: return fail("参数格式错误", 400), 400。

2. 404 兜底后，前端只需判断 `code == 0`，其余一律弹 msg。

3. 用 Flask-RESTful / 蓝图 时，错误处理器要按蓝图挂载（@bp.errorhandler），注意与主 app 的区分。

4. 统一返回 JSON 后，页面模板渲染要另做；纯 API 项目用 flask jsonify 或在 after_request 里统一加 Content-Type: application/json。

一句话：辅助函数 + errorhandler(404/500) 三件套，就能让所有接口输出同一套 JSON 结构。