Flask-SQLAlchemy 必须先创建 app 实例再调用 db.init_app(app)，否则报 RuntimeError；模型需显式定义 __tablename__；db.session.add() 后必须 commit() 才生效；查询结果为模型实例，JSON 序列化前需转字典。
Flask-SQLAlchemy 初始化时 db.init_app(app) 必须在创建 app 实例之后调用
很多新手把 db = SQLAlchemy() 和 db.init_app(app) 写在模块顶层，但 app 还没造出来，结果运行就报 RuntimeError: Working outside of application context。
根本原因是 Flask-SQLAlchemy 需要绑定到一个已配置的 app 对象才能读取数据库配置、初始化连接池。直接 SQLAlchemy(app) 虽然能跑，但不利于应用工厂（Application Factory）模式，也不方便单元测试。
- ✅ 正确做法：先
app = Flask(__name__)，再db.init_app(app) - ❌ 错误写法：
db = SQLAlchemy(app)放在 import 后、app 创建前；或漏掉init_app直接用db - ⚠️ 注意：如果用了蓝本（Blueprint），也要确保
db在蓝本导入前已完成初始化，否则模型定义会找不到db元数据
定义模型类时 __tablename__ 不写会触发隐式命名，但表名可能不符合预期
Flask-SQLAlchemy 默认用类名小写作为表名（如 User → user），看起来省事，但实际项目中很容易踩坑：比如类名是 HTTPLog，生成表名是 httplog，而不是更清晰的 http_log；或者多个模型类名缩写冲突（APIKey 和 ApiKey 都变 apikey）。
显式声明 __tablename__ 是最小成本的可控性保障，尤其涉及已有数据库或团队协作时。
立即学习“Python免费学习笔记（深入）”；
- ✅ 推荐写法：
__tablename__ = "user_profile"，下划线风格，与 PostgreSQL/MySQL 实际习惯对齐 - ❌ 不要依赖默认：除非你确认所有模型类名都符合 snake_case 且无歧义
- ⚠️ 特别注意：一旦表已存在，改
__tablename__不会自动重命名表，需手动迁移或用alembic
db.session.add() 后不 commit()，数据永远不会进库
这是最常被忽略的“断层”：加了对象、没提交、也没报错，查数据库空空如也。Flask-SQLAlchemy 的 session 是事务级缓存，add() 只是标记为“待插入”，真正落盘靠 commit()。
更麻烦的是，如果中途出错没 rollback()，session 会卡在异常状态，后续操作全抛 InvalidRequestError。
- ✅ 安全写法：用
try...except包住add+commit，失败时db.session.rollback() - ✅ 简单场景可用
db.session.add_all([obj1, obj2])批量添加，仍需commit() - ⚠️ 切勿用
db.create_all()代替commit()：它只建表结构，不处理 session 数据 - ⚠️
db.session.flush()会把 SQL 发给数据库但不提交，调试时有用，但生产环境慎用
查询返回的是模型实例，不是字典 —— 想 JSON 序列化得先转
写 User.query.filter_by(id=1).first() 得到的是 User 对象，直接 jsonify() 会报 TypeError: Object of type User is not JSON serializable。这不是 Flask 的 bug，是 Python 原生限制。
有人用 .__dict__ 硬转，但会带一堆 SQLAlchemy 内部字段（如 _sa_instance_state），还可能漏掉关系字段或触发懒加载异常。
- ✅ 干净做法：在模型里加个
to_dict()方法，显式控制字段（例如return {"id": self.id, "name": self.name}） - ✅ 更省事：用
sqlalchemy.orm.attributes.instance_dict(obj)获取纯净字段，但不含关系数据 - ⚠️ 关系字段（如
user.posts）默认懒加载，直接访问可能引发额外查询，甚至 N+1 问题；需要时用joinedload预加载
