直接用 json.dumps() 会出错，因 python 原生 json 模块仅支持 dict/list/str/int/float/none/bool，不处理 datetime、sqlalchemy 模型或 decimal 等类型，导致 typeerror；flask 默认 jsonify() 底层仍调用该模块，故同样报错。
直接用 json.dumps() 处理 Flask 响应里的 datetime、SQLAlchemy 模型或嵌套对象，99% 会抛 TypeError: Object of type datetime is not JSON serializable。这不是 Flask 问题，是 Python 原生 json 模块的硬限制——它只认 dict/list/str/int/float/None/bool。
为什么 Flask 默认 json.dumps() 总是报错
Flask 3.x 的 jsonify() 底层仍调用 json.dumps()，没做额外类型适配。一旦你返回的是 datetime、Decimal、SQLAlchemy 实例、自定义类，甚至带循环引用的字典，就立刻崩。
-
jsonify(Post.query.first())→Object of type Post is not JSON serializable -
jsonify({"ts": datetime.now()})→Object of type datetime is not JSON serializable -
jsonify({"data": Decimal('12.34')})→ 同样报错（Decimal不在原生支持列表里）
用 custom JSONEncoder 是最轻量的兜底方案
适合简单项目或临时修复，不用引入新依赖。核心是重写 default() 方法，把不支持的类型转成能序列化的形式。
- 继承
flask.json.JSONEncoder（注意：不是json.JSONEncoder），并在app.json_encoder = YourEncoder中注册 -
datetime和date统一转isoformat()，前端解析最稳 -
Decimal转float或str，按业务选；转float有精度丢失风险 - SQLAlchemy 模型不能直接 dump，得先转 dict —— 但别用
obj.__dict__，会带_sa_instance_state；改用vars(obj)+ 过滤私有字段，或显式取obj.__table__.columns
示例：
from flask import Flask
from datetime import datetime
from decimal import Decimal
<p>class CustomJSONEncoder(flask.json.JSONEncoder):
def default(self, obj):
if isinstance(obj, datetime):
return obj.isoformat()
if isinstance(obj, Decimal):
return float(obj) # 或 str(obj)
if hasattr(obj, '<strong>table</strong>'): # SQLAlchemy 模型
return {c.name: getattr(obj, c.name) for c in obj.<strong>table</strong>.columns}
return super().default(obj)</p><p>app = Flask(<strong>name</strong>)
app.json_encoder = CustomJSONEncoder
</p>
Marshmallow 是复杂场景的真正解法
当你需要字段级控制（比如 admin 接口返回 email，public 接口不返回）、反序列化校验、跨关系取值（author.name）、多版本输出（v1/v2 字段不同），json.dumps() + JSONEncoder 就力不从心了。
- 别用已弃用的
ModelSchema，直接继承Schema，字段声明即契约 -
fields.DateTime(format='iso')比手动转字符串更可靠，自动处理时区和 None -
attribute='author.name'支持点号路径，比@post_dump更简洁，适合单向序列化 - schema 实例复用：在模块顶层定义
post_schema = PostSchema()，别每次请求 new 一个
最小可用写法：
from marshmallow import Schema, fields
from datetime import datetime
<p>class PostSchema(Schema):
id = fields.Integer()
title = fields.String()
created_at = fields.DateTime(format='iso')
author_name = fields.String(attribute='author.name')</p><h1>视图中</h1><p>@app.route('/posts')
def list_posts():
posts = Post.query.all()
return jsonify(post_schema.dump(posts, many=True))
</p>
容易被忽略的兼容性细节
Flask 3.x 默认启用 app.json（基于 click.utils.get_json），但如果你手动设置了 app.json_encoder，它会被绕过；而 Marshmallow 需要显式调用 .dump()，不会走 Flask 的 JSON 路径。这两套机制不自动兼容。
- 混合使用时，确保
jsonify()只接收 dict/list，别传 model 或 datetime - 用
flask.json.provider.DefaultJSONProvider替代老式JSONEncoder是 Flask 3.x 推荐方式，但迁移成本略高 - 时间格式别用
format='timestamp'：Unix 时间戳没时区信息，前端 new Date(1718505600) 可能错 8 小时
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
