Flask-SQLAlchemy 中的传统查询接口详解

Flask-SQLAlchemy 中的传统查询接口详解

flask-sqlalchemy Adds SQLAlchemy support to Flask 项目地址: https://gitcode.com/gh_mirrors/fl/flask-sqlalchemy

传统查询接口概述

在 Flask-SQLAlchemy 项目中，传统查询接口为开发者提供了一种便捷的方式来与数据库交互。虽然 SQLAlchemy 官方已将其标记为"传统"（legacy），但在许多现有项目中仍然广泛使用。

传统查询接口的核心特点是它为每个模型类自动添加了一个 query 属性，这使得我们可以直接通过模型类进行查询，而不必每次都显式地使用会话对象。

基本查询方法

通过主键查询

# 获取ID为5的用户
user = User.query.get(5)

这种方式简单直接，适用于已知主键值的情况。如果找不到对应记录，会返回 None。

条件查询

# 通过用户名获取用户
user = User.query.filter_by(username=username).one()

filter_by 方法用于简单的等值条件查询，而 filter 方法则支持更复杂的条件表达式。one() 方法确保查询结果只有一条记录，否则会抛出异常。

视图中的便捷查询方法

在 Web 开发中，处理不存在的资源时返回 404 错误是常见需求。Flask-SQLAlchemy 为此提供了几个特别有用的方法：

get_or_404

user = User.query.get_or_404(user_id)

如果找不到指定ID的记录，自动返回 404 响应，否则返回对应的模型实例。

first_or_404

latest_post = Post.query.order_by(Post.created.desc()).first_or_404()

当查询可能返回空结果集时使用，确保要么返回第一条记录，要么返回 404。

one_or_404

user = User.query.filter_by(username=username).one_or_404()

确保查询结果有且只有一条记录，否则返回 404。特别适合通过唯一字段查询的场景。

这些方法都可以附加自定义的错误描述：

user = User.query.filter_by(username=username).one_or_404(
    description=f"找不到用户名为 '{username}' 的用户"
)

分页处理

对于可能返回大量结果的查询，分页是必不可少的。Flask-SQLAlchemy 提供了强大的分页支持：

page = User.query.order_by(User.join_date).paginate()

paginate() 方法默认从请求的查询参数中获取 page（当前页码）和 per_page（每页条数）值，默认是第一页，每页20条。

分页对象属性

分页返回的 Pagination 对象包含以下有用属性：

• items: 当前页的记录列表
• page: 当前页码
• per_page: 每页条数
• total: 总记录数
• pages: 总页数
• prev_num/next_num: 上一页/下一页的页码
• has_prev/has_next: 是否有上一页/下一页

分页控制

可以显式指定分页参数：

page = Post.query.paginate(page=2, per_page=10, max_per_page=50)

max_per_page 参数可以防止用户请求过多的单页数据，保护系统性能。

传统查询与现代查询的对比

虽然传统查询接口简单易用，但 SQLAlchemy 官方推荐使用新的查询风格：

# 传统方式
users = User.query.filter(User.age > 18).all()

# 现代方式
from sqlalchemy import select
users = db.session.execute(select(User).where(User.age > 18)).scalars().all()

新方式更符合 SQLAlchemy 2.0 的设计理念，提供了更好的类型提示支持和更清晰的表达式语法。

最佳实践建议

1. 在新项目中，考虑优先使用现代查询方式
2. 在现有项目中，可以逐步迁移到新语法
3. 视图中的 *_or_404 方法仍然非常实用，可以继续使用
4. 分页功能无论新旧查询方式都适用

理解这些查询方法的工作原理和适用场景，将帮助开发者更高效地使用 Flask-SQLAlchemy 进行数据库操作。

flask-sqlalchemy Adds SQLAlchemy support to Flask 项目地址: https://gitcode.com/gh_mirrors/fl/flask-sqlalchemy