Flask如何分页显示数据库？，有哪些方法？

核心结论

Flask分页显示数据库的推荐方案是使用Flask-SQLAlchemy自带的paginate()方法，它通过接收当前页码和每页数量返回一个Pagination对象，自动处理OFFSET和LIMIT逻辑，并提供当前页数据、总页数、前后页链接等属性，无需手动拼接SQL即可快速实现分页显示。参考2

分页实现基础：三步搭建核心逻辑

安装与模型准备

首先确保项目中已安装Flask-SQLAlchemy,在虚拟环境中执行：

加载中

Flask编程进阶：SQLite数据列表分页查询的绝佳方法

程序员领队

260--

原视频地址

pip install flask-sqlalchemy

假设我们有一个用户表,模型定义如下：

from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    email = db.Column(db.String(100))

视图函数中的分页调用

在路由视图函数中，需要从请求参数中获取页码（page）和每页数量（per_page），然后对模型进行分页查询,核心代码：

from flask import request, render_template
@app.route('/users')
def users():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 10, type=int)
    pagination = User.query.paginate(page=page, per_page=per_page, error_out=False)
    users = pagination.items
    return render_template('users.html', pagination=pagination, users=users)

• page：当前页码，从查询字符串获取,默认第1页。
• per_page：每页显示条数,默认10条。
• error_out=False：当页码超出范围时不报错，返回空列表,便于前端处理。
• pagination.items：当前页的数据列表。

模板中的分页导航

在模板中，需要显示数据列表和分页导航链接,以下是一个常见的分页导航片段：参考2

<table>
    {% for user in users %}
    <tr>
        <td>{{ user.id }}</td>
        <td>{{ user.name }}</td>
        <td>{{ user.email }}</td>
    </tr>
    {% endfor %}
</table>
<div class="pagination">
    {% if pagination.has_prev %}
        <a href="{{ url_for('users', page=pagination.prev_num) }}">上一页</a>
    {% endif %}
    {% for page_num in pagination.iter_pages() %}
        {% if page_num %}
            <a href="{{ ur
l_for('users', page=page_num) }}" 
               class="{{ 'active' if page_num == pagination.page else '' }}">
                {{ page_num }}
            </a>
        {% else %}
            <span>...</span>
        {% endif %}
    {% endfor %}
    {% if pagination.has_next %}
        <a href="{{ url_for('users', page=pagination.next_num) }}">下一页</a>
    {% endif %}
</div>

• pagination.has_prev / has_next：判断是否有上一页/下一页。
• pagination.prev_num / next_num：上一页/下一页的页码。
• pagination.iter_pages()：生成分页页码列表，中间页码用……替代。

代码实战：从模型到模板的完整示例

分页参数详解

paginate()返回的Pagination对象包含以下核心属性：

完整代码示例：博客文章列表分页

假设我们有一个Post模型,需要分页显示文章列表：

@app.route('/posts')
def posts():
    page = request.args.get('page', 1, type=int)
    per_page = 10
    pagination = Post.query.order_by(Post.created_at.desc()).paginate(
        page=page, per_page=per_page, error_out=False
    )
    posts = pagination.items
    return render_template('posts.html', pagination=pagination, posts=posts)

模板中展示文章标题和摘要，分页导航复用之前的代码，注意error_out=False，这样即使页码超出范围，也能正常渲染页面,只是数据为空。

处理不同场景下的分页参数

• 搜索结合分页：在分页查询前先应用过滤条件，例如Post.query.filter(Post.title.contains(keyword)).paginate(...)，同时需要将搜索关键词保留在分页链接中，通过url_for手动拼接参数。
• 排序与分页：分页前务必先排序，否则分页结果可能不固定，使用order_by确保顺序一致。
• 每页数量动态调整：可以从请求参数中获取per_page，但需要做合法性校验，防止用户传入过大值导致性能问题，通常设置上限，如per_page = min(per_page, 100)。

性能优化与常见问题

大数据量下的分页性能

当数据量达到百万级时，传统的OFFSET分页效率会下降，因为数据库需要扫描并丢弃前N条记录，行业共识认为,对于这种场景有两种优化方向：

• 键集分页（Keyset Pagination）：通过上次查询的最后一条记录的某个字段（如ID）来定位下一页起点，避免扫描跳过的行，但实现相对复杂,且不支持随机跳页。
• 增加缓存层：对分页结果进行缓存，减少重复查询,常用Redis缓存热点页。

对于大多数中小型应用（总记录数在几万以内），直接使用paginate()性能完全足够,无需过度优化。

常见错误与规避

• 页码超出范围：设置error_out=False，让视图返回空列表而非404，前端可显示“没有更多数据”或隐藏分页控件。
• 每页数量设置不当：per_page不宜过大（如超过100），否则单次查询加载大量数据会拖慢页面加载速度，建议根据列表展示密度设置在10-30之间。
• 分页导航显示不全：当总页数很多时，iter_pages()默认只生成左右各两页的链接，中间用None表示省略，如果希望显示更多页码，可以自定义iter_pages的参数，如pagination.iter_pages(left_edge=2, left_current=2, right_current=3, right_edge=2)。
• 分页链接中的参数丢失：在模板中生成分页链接时，除了page参数，还需要保留其他查询参数（如搜索词、排序字段），可以在url_for中传入request.args并覆盖

  

  page，url_for('posts', request.args, page=page_num)。

分页方案对比：Flask与Django的异同

如果你从Django转向Flask，可能对分页的实现方式感到好奇，在Django中，分页使用Paginator类，与Flask-SQLAlchemy的paginate()非常相似,但有两个关键区别：

• 查询对象：Flask的paginate()是直接绑定在查询对象上的方法，而Django需要先创建Paginator实例，再调用get_page()。
• 模板渲染：Django的Paginator对象提供了page_obj，属性命名与Flask略有不同（如has_previous vs has_prev），但整体设计思路一致,都是通过当前页对象获取数据列表和分页信息。

在性能上，两者底层均依赖数据库的LIMIT/OFFSET，没有本质差异，选择哪种框架取决于你的技术栈,而非分页功能本身。

Flask分页显示数据库的核心就是paginate()方法，它封装了分页所需的全部逻辑，从数据截取到导航信息生成，熟练掌握其参数（page、per_page、error_out）和Pagination对象属性（items、pages、iter_pages()），即可在多数场景下快速实现清晰、高效的分页显示。

常见问题与解答

Flask分页显示数据库时如何获取总页数？

通过pagination.pages属性获取，它返回总页数（整数），例如pagination.pages的值就是总页数，可用于在模板中展示“共X页”。

Flask分页显示数据库如何自定义每页显示数量？

在调用paginate()时传入per_page参数，如User.query.paginate(page=1, per_page=20)，也可以从请求参数中获取，例如request.args.get('per_page', 10, type=int)，但需验证数值范围,防止恶意传入过大值导致性能问题。

Flask分页显示数据库在模板中如何生成页码链接？

使用url_for函数生成带page参数的链接，遍历pagination.iter_pages()返回的页码列表，如果是数字则生成链接，如果是None则显示省略号，同时利用pagination.has_prev和pagination.has_next控制上一页/下一页的显示，并分别传入pagination.prev_num和pagination.next_num作为页码。