marshmallow 是解决 flask 中 sqlalchemy 模型 json 序列化问题的最稳方案，需确保 schema 字段与模型属性一致、显式加载关联数据、正确使用 dump() 而非 dumps()、统一时区为 utc。
Model 转字典时字段丢失或报错 Object of type User is not JSON serializable
Flask 默认不处理 ORM 实例的序列化，直接 jsonify(user) 会触发这个错误。根本原因是 SQLAlchemy 模型不是原生 Python 字典，JSON 模块不认识它。
用 Marshmallow 是最稳的解法，但别直接对模型实例调 schema.dump() 就完事——得先确保 schema 正确绑定字段：
- 字段名必须和模型属性名一致，或显式用
attribute=映射（比如模型里是user_name，想序列化成username） - 外键关系字段默认不导出，要加
fields.Nested或fields.List并配对应 schema - 避免在 schema 里写不存在的模型属性，否则
dump()会静默跳过或抛AttributeError
示例：UserSchema 中若漏写 id 字段，dump() 后字典就真没 id，前端可能报错。
一对多关系嵌套导出时数据重复或空列表
比如 User 有多个 Post，用 posts = fields.List(fields.Nested(PostSchema)) 后返回空列表，常见原因不是代码写错，而是查询没加载关联数据。
SQLAlchemy 默认懒加载，session.query(User).get(1) 只查了 user 表，user.posts 在 dump() 时才触发查询——但如果 session 已关闭，就会得到空列表或报 DetachedInstanceError。
- 查数据时显式用
joinedload或selectinload：例如session.query(User).options(selectinload(User.posts)).get(1) - 别依赖
lazy='dynamic'的关系，fields.List无法自动 resolve query 对象 - 如果只是需要 ID 列表，用
fields.List(fields.Integer(), attribute='post_ids')配合模型里的@hybrid_property更轻量
dump() 和 dumps() 选哪个？性能差在哪
两者都走相同序列化逻辑，区别只在输入类型和输出格式：dump() 输入单个对象或列表，输出 dict/list；dumps() 输入同上，但强制输出 str（即 JSON 字符串）。
多数场景该用 dump()，因为 jsonify() 内部会再做一次 JSON 编码。如果误用 dumps()，等于双重编码，返回的是被转义的字符串（比如 "{\"name\": \"alice\"}"），前端 JSON.parse() 会失败。
- 单对象：用
schema.dump(user)→ 传给jsonify() - 列表：用
schema.dump(users, many=True)，别写成schema.dumps(users, many=True) - 如果绕过
jsonify直接写响应体（如流式 API），才考虑dumps()
日期字段序列化成字符串后时区不对
SQLAlchemy 的 DateTime 字段默认无时区信息，Marshmallow 的 fields.DateTime 默认按本地时区解析，但 Flask 响应头通常设为 UTC，前后端时间显示就可能差 8 小时。
关键不是改格式，而是统一时区上下文：
- 数据库存 UTC 时间（推荐），模型字段用
DateTime(timezone=True)，配合func.now()或datetime.utcnow() - schema 中显式指定时区：
fields.DateTime(format='iso', default_timezone=timezone.utc) - 避免用
format='timestamp'，它返回 int，在 JS 里容易误当成毫秒（实际是秒）
时区问题一旦埋下，后期排查成本远高于初始化时加两行配置。
