filter_by()仅支持列名=值的精确匹配，列名须为合法标识符；filter()支持模糊查询、比较运算、关联字段等复杂条件。
filter_by() 和 filter() 的区别在哪？
很多人一上来就用 filter_by()，结果查不到数据，其实是搞混了它和 filter() 的适用场景。filter_by() 只支持「列名=值」这种精确等值匹配，且列名必须是 Python 合法标识符（不能是表达式、函数或带下划线的特殊字段别名）；filter() 才支持更灵活的条件，比如模糊查询、比较运算、关联字段访问。
常见错误现象：AttributeError: 'User' object has no attribute 'created_at__gt' —— 这是因为有人试图写 filter_by(created_at__gt=datetime.now())，但 filter_by() 压根不认双下划线语法。
-
filter_by(name="alice")✅ 安全、简洁，适合单字段精确匹配 -
filter(User.name.like("%ali%"))✅ 必须用filter()+ 模型类引用 -
filter(User.status == "active", User.created_at > yesterday)✅ 多条件组合也得走filter() - 如果模型用了
__tablename__ = "user_info"，但字段名仍是name，filter_by()仍按模型属性名找，不是数据库列名
all() 是不是每次都会触发新查询？
是的，只要没缓存，每次调用 all() 都会发一次 SQL。但它本身不执行查询，只是把 Query 对象转成 Python 列表——真正执行在第一次取值时（懒加载）。容易被忽略的是：它不支持分页，也不做结果集限制，大数据量下直接 OOM。
使用场景：你确定结果不会超过几百条，且后续要遍历全部对象做复杂逻辑（比如逐个调用方法、拼装嵌套结构）。
- 不要在视图里无脑写
User.query.filter_by(active=True).all()，尤其当User表有几十万行 - 想“只取一条”？用
first()或one_or_none()，比all()[0]安全得多（后者空列表会报IndexError） - 需要总数？用
count()，别len(all())，前者走 COUNT(*)，后者把全量数据拉到内存再算长度 -
all()返回的是 list，不是 Query，之后不能再链式调用order_by()或limit()
查出来是空列表，但数据库明明有数据？
最常见原因是 session 未提交或事务隔离问题。Flask-SQLAlchemy 默认用 scoped_session，如果你在另一个线程/请求上下文里插入了数据但没 db.session.commit()，当前查询看不到；或者用了 db.session.begin_nested() 但没正确回滚/提交，也会导致不一致。
另一个高频坑是字段类型不匹配：比如数据库里 status 是 ENUM('active','inactive')，但代码里传字符串 "Active"（大小写敏感），filter_by(status="Active") 就查不到。
- 先确认是否 commit：在插入后加
print(db.session.new, db.session.dirty)，非空说明还没刷进 DB - 用
db.session.execute("SELECT * FROM user WHERE status = 'active'").fetchall()绕过 ORM 直接查，验证是不是 ORM 层的问题 - 检查模型定义里字段类型，比如
String(50)和数据库实际长度不符，可能导致隐式截断或匹配失败 - MySQL 默认不区分大小写，但 PostgreSQL 区分；ORM 不会帮你自动 lower()/upper()，得显式写
func.lower(User.name) == "alice"
为什么有时候 .all() 返回空，但 .count() > 0？
这通常意味着查询条件里混用了不同模型的字段，而 SQLAlchemy 自动做了 JOIN，但没指定 ON 条件，导致笛卡尔积 + WHERE 过滤后结果为空，但 COUNT(*) 走的是优化路径（可能只扫索引）。更隐蔽的情况是：你在 filter() 里用了子查询或关联属性，但关联关系没正确定义（比如漏写 backref 或 foreign_keys），SQL 生成异常。
- 开启 SQL 日志：
app.config['SQLALCHEMY_ECHO'] = True，看实际发出的 SELECT 和 COUNT 语句是否一致 - 把
.all()换成.statement.compile(compile_kwargs={"literal_binds": True})打印出完整 SQL，复制到数据库客户端里手动执行对比 - 避免在 filter 中直接用
RelatedModel.field，除非已定义好 relationship；否则老实用join()显式声明连接 - 如果用了
query.options(joinedload(User.profile))，但User没对应profile记录，整个all()可能返回空（取决于 outerjoin 设置），而count()不受影响
最麻烦的不是语法错，而是查询逻辑和数据库状态之间的微妙偏差——比如软删除字段没在 filter 里排除，或者时间范围跨了时区却没统一转 UTC。
