怎么在Python Flask应用中统一API返回数据格式-Python教程-PHP中文网

不能直接 return dict，因Flask虽自动jsonify顶层dict/list，但嵌套自定义对象（如ORM模型、datetime、Decimal）会抛TypeError；且手动拼接{"code":0,"data":...,"msg":"ok"}易漏字段、状态码不一致、命名混乱（msg/message），导致前端兼容成本高。

怎么在python flask应用中统一api返回数据格式

为什么不能直接 return dict？

Flask 默认返回字典时会调用 jsonify()，但仅限于顶层是 dict 或 list；如果中间嵌套了自定义对象（比如 ORM 模型实例）、datetime、Decimal，就会抛出 TypeError: Object of type X is not JSON serializable。更关键的是，不同接口手动拼 {"code": 0, "data": ..., "msg": "ok"} 容易漏字段、错状态码、不一致——比如有的写 message，有的写 msg，前端得写一堆兼容逻辑。

用 @app.after_request 统一包装响应体

这是最轻量、侵入性最小的方式，适合已有项目快速收敛格式。核心思路：拦截所有 application/json 响应，只处理未被标记为“已格式化”的响应体。

在视图函数里返回原始数据前，加个标记，比如设置 response.is_api_response = True
在 @app.after_request 中检查这个标记，若存在且响应 Content-Type 是 JSON，则用标准结构包裹 response.get_json()，再重新序列化
注意：不能直接修改 response.data 字符串，要调用 jsonify() 重建响应对象，否则中文乱码或 headers 错乱

@app.after_request
def format_api_response(response):
    if getattr(response, 'is_api_response', False) and 'application/json' in response.content_type:
        try:
            original_data = response.get_json()
            formatted = {
                "code": 0,
                "data": original_data,
                "msg": "success"
            }
            return jsonify(formatted)
        except Exception:
            pass  # 非法 JSON 不处理，避免雪崩
    return response

封装统一的 success() / fail() 工具函数

比装饰器更可控，也更容易测试。重点不是“多写一个函数”，而是强制约束返回路径——所有 API 接口必须通过这两个函数退出。

阿拉丁·前端工程工坊｜脚手架·组件·规范落地·构建优化·性能与可访问性一体

阿拉丁·前端工程工坊把「前端只会写页面、规范停在文档里、脚手架手敲、构建靠抄、性能靠猜、可访问性靠忘」从「手动搭项目、抄配置、肉眼查规范」升级成一条本地工具链——多框架脚手架生成(React/Vue3/Svelte + Vite)、可复用组件生成(Props 类型+样式+示例)、规范落地检查(lint-lite:命名/未用变量/console残留/TS any/目录结构)、构建配置生成与产物体积预算、性能审计(依赖体积/重复/懒加载/Lighthouse 清单)、可访问性(a11y)校验(alt/aria

下载

success(data=None, msg="success", code=0)：自动处理 datetime、Decimal 等常见非序列化类型（用 default 参数传给 json.dumps）
fail(msg="error", code=-1, data=None)：错误码和消息分离，便于前端 switch code 做差异化提示
不要在工具函数里做日志或鉴权，那是中间件的事；这里只干一件事：序列化 + 包装
避免把数据库对象直接传给 data，先转成 dict 或用 schema 序列化（如 model.to_dict()）

from flask import jsonify
from decimal import Decimal
import json
from datetime import datetime
<p>def json_default(obj):
if isinstance(obj, datetime):
return obj.isoformat()
if isinstance(obj, Decimal):
return float(obj)
raise TypeError(f"Object of type {type(obj)} is not JSON serializable")</p><p>def success(data=None, msg="success", code=0):
return jsonify({
"code": code,
"data": data,
"msg": msg
}), 200, {'Content-Type': 'application/json; charset=utf-8'}</p><p>def fail(msg="error", code=-1, data=None):
return jsonify({
"code": code,
"data": data,
"msg": msg
}), 200, {'Content-Type': 'application/json; charset=utf-8'}
</p>