Flask使用flask-sqlalchermy分页查询total值与数据库不符问题

问题本质 #

你遇到的现象——传入per_page=10时返回total=9，传入per_page=20时返回total=19，和数据库直接查的全量结果19对不上——核心原因是Flask-SQLAlchemy的分页方法没有正确执行独立的全量count统计，直接把带LIMIT截断的当前页查询结果当成了总条数，没有跑无分页限制的全量计数。

分步解决方式 #

• 先排查版本兼容问题
  这是该场景最高发的诱因：Flask-SQLAlchemy 2.1.x及更早版本和SQLAlchemy 1.3+版本存在API不兼容。旧版分页逻辑计算total时，需要从原查询中剥离limit、offset子句再执行count，但受新版SQLAlchemy的查询结构变更影响，旧代码无法正确剥离limit条件，导致count查询本身带了和per_page一致的LIMIT限制，最终统计值自然和传入的per_page参数挂钩。
  处理方式：将Flask-SQLAlchemy升级到2.5及以上稳定版本，或降级SQLAlchemy到1.2.x的匹配版本即可解决。
• 绕过框架默认的total计算逻辑
  如果调整版本后问题仍然存在，可以在代码里显式单独执行全量count计算，手动把统计值传入分页方法，绕开框架自带的total统计逻辑。示例代码：

  # 构造基础查询，不要加排序、分页条件
  base_query = db.session.query(agent).filter(...)
  # 手动计算全量总条数
  total_count = base_query.count()
  # 再执行带排序的分页查询，传入手动计算的total值
  page = base_query.order_by(agent.create_time).paginate(
      page=1,
      per_page=10,
      total=total_count
  )
  

• 排查查询结构异常
  如果手动count的结果和数据库直接查询的结果仍有偏差，需要检查原查询是不是存在联表关联一对多结构的情况：这类场景会导致同一条主表记录出现重复行，框架默认的count逻辑不会自动去重，也会造成total值不准。这种情况需要在count查询里显式加去重逻辑：

  # 联表导致记录重复时，用主键去重后再统计
  total_count = db.session.query(agent.id).filter(...).distinct().count()
  

内容的提问来源于stack exchange，提问作者Jax