db.session.add() 仅标记对象为待插入，必须调用 db.session.commit() 才真正执行SQL写入数据库；未commit则数据不存在、id为None、查询返回None，且事务需手动管理以避免脏状态。
db.session.add() 之后不 commit()，数据根本不会进数据库
很多人以为 db.session.add() 就等于“保存成功”，其实它只是把对象标记为“待插入”，真正写入要靠 db.session.commit()。没调用 commit()，哪怕程序跑完、服务重启，这条记录也不存在——不是延迟写入，是压根没发 SQL。
常见错误现象：add() 后直接查（比如 Model.query.filter(...).first()），结果返回 None；或者调试时打印 obj.id 是 None，因为主键是在 commit() 后才由数据库生成并回填的。
- 必须成对使用：
add()+commit()，缺一不可 - 如果中途出错（比如字段唯一冲突），
commit()会抛出IntegrityError，此时 session 进入失效状态，后续操作需先db.session.rollback() - 不要在循环里每条都
commit()——性能极差；批量插入建议用db.session.bulk_save_objects()或原生execute()
增删改查都要走 session，但 delete() 和 update() 的写法容易错
delete() 不是模型方法，而是 session 方法：得传入实例，不能传查询条件。比如 db.session.delete(user) 正确，User.query.filter_by(id=1).delete() 虽然能执行，但那是“无 session 的直连删除”，绕过 ORM 生命周期（如 @hybrid_property、事件钩子），且不触发级联逻辑（除非显式配置 cascade='all, delete-orphan'）。
update() 同理：ORM 中没有“一行 update 语句”的便捷接口。想改字段，得先 query.get() 或 filter().first() 拿到实例，再赋值，最后 commit()。
- 安全删：先查再删 ——
user = User.query.get(1); db.session.delete(user); db.session.commit() - 避免直删：不用
User.query.filter(...).delete(synchronize_session=False)，除非你明确知道它跳过 session 管理 - 更新字段：别写
user.name = 'new'后漏掉commit()；ORM 不会自动感知变更并提交
事务边界不清晰，导致部分成功、部分失败却没回滚
Flask 默认不开启自动事务，每个请求里 db.session 是独立的，但不会自动 commit() 或 rollback()。如果你在一个视图函数里做了多次 DB 操作，其中某步出错（比如网络异常、校验失败），而你只捕获了异常却忘了 rollback()，session 就卡在脏状态，下次用这个 session 会报 TransactionFailed 或更隐蔽的脏读。
正确做法是用上下文管理或显式控制：
- 推荐用
try/except/finally：成功则commit()，异常则rollback()，finally里不做 session 清理（Flask-SQLAlchemy 会在请求结束时自动remove()） - 不要依赖
@app.teardown_appcontext做统一 commit——它无法区分哪些操作该提交、哪些该丢弃 - 复杂业务逻辑建议封装进 service 函数，并强制要求调用方处理事务，而不是在 route 层堆砌 DB 调用
Flask-SQLAlchemy 的 session 作用域常被当成全局变量滥用
db.session 是线程/请求局部的，但在多线程环境（比如 Celery 任务、后台线程）中直接用它会出问题：可能复用其他请求的 session，或引发 AttributeError: 'scoped_session' object has no attribute 'add'。这不是 bug，是设计使然——scoped_session 依赖上下文栈，而线程没有 Flask 请求上下文。
典型场景：异步发邮件后更新订单状态，或定时任务同步数据。这时候必须手动创建新 session，或用 db.create_scoped_session() 配合 bind 显式管理。
- 后台任务里别直接用
db.session，改用db.sessionmaker(bind=db.engine)()创建新 session - 测试时（如 pytest）也要注意：每个 test case 应该有独立 session，否则前一个 test 的未 commit 数据会影响后一个
- 别在模块顶层或类属性里缓存
db.session，它不是静态对象
