Flask-SQLAlchemy 的 paginate 方法在大数据量下性能极差，因其底层使用 OFFSET-LIMIT 导致全表扫描；应改用游标分页，依赖排序字段值而非页码，并禁用 total 计算、限制 page 上限。
Flask-SQLAlchemy 的 paginate 方法默认不支持大数据偏移分页
直接调用 query.paginate(page=1000, per_page=20) 在数据量大（比如千万级）时会极慢，甚至超时。这是因为底层执行的是 OFFSET 19980 LIMIT 20 —— 数据库必须扫描并跳过前 19980 行，而不管是否用得上。
这不是 Flask 或 paginate 的 bug，而是 SQL 标准分页的固有缺陷。真实场景中，page 超过几百就该警惕性能崩塌。
- MySQL 5.7+、PostgreSQL 12+ 对大 OFFSET 的优化有限，别指望数据库自动加速
-
paginate返回的.pages和.total会触发COUNT(*)全表扫描，千万级表可能卡死连接 - 前端传来的
page=10000不代表你真要查第 10000 页，很可能是爬虫或误操作，应主动拦截
用游标分页（cursor-based pagination）替代 page/offset
放弃页码，改用「上次查询最后一条记录的排序字段值」作为下一页起点。例如按 id 升序分页：
# 第一页（无 cursor） items = db.session.query(User).order_by(User.id).limit(20).all() <h1>下一页：取上一页最后一条的 id，查 > 该 id 的前 20 条</h1><p>last_id = items[-1].id if items else 0 next_items = db.session.query(User).filter(User.id > last_id).order_by(User.id).limit(20).all()
- 必须有确定的、高选择性的排序字段（如主键
id或带索引的时间戳created_at） - 不能跳页，只能“下一页”“上一页”，但换来的是 O(1) 查询复杂度
- 避免使用
ORDER BY RAND()或多字段不稳定排序（如ORDER BY status, id且status值重复多） - 前端需保存并透传
cursor（如 base64 编码后的last_id），而不是page参数
如果非要用 paginate，至少关掉 total 计算和错误页码兜底
Flask-SQLAlchemy 的 paginate 默认强制查总数，且对越界页码返回空列表而不报错，容易掩盖问题。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
- 加
error_out=False防止 404，但你要自己判断pagination.items是否为空 - 用
count=False（SQLAlchemy 3.0+）或降级为max_per_page+ 手动限制，跳过COUNT(*) - 对
page做硬限制：if page > 200: abort(400, "page too large") - 在日志里记录高 page 值请求，用于识别恶意扫描或前端 bug
注意 paginate 在不同 SQLAlchemy 版本的行为差异
SQLAlchemy 2.0+（配合 Flask-SQLAlchemy 3.0+）把 paginate 改成了返回 Pagination 对象，但关键参数名变了：
- 旧版（SA 1.4 / FSA 2.x）：
query.paginate(page=1, per_page=20, error_out=True) - 新版（SA 2.0+ / FSA 3.0+）：
query.paginate(page=1, per_page=20, error_out=True, max_per_page=100)，多了max_per_page防爆 - 新版默认
count=True，但若显式传count=False，则.total和.pages永远为None，别再依赖它们做分页控件渲染 - 如果你用的是
select()对象（不是 legacy Query），得先调用session.execute(select(...)).scalars().all()，不能直接.paginate()
游标分页没有银弹，但它是唯一能在线上扛住亿级数据的分页方式。page 参数看着直观，代价是数据库的喘息时间——这点常被开发初期忽略。
