1、为什么可以用 模型类.query 来查询数据库？

在 Flask 中使用 SQLAlchemy ORM 时，所有继承自 db.Model 的模型类都会自动获得一个 query 属性。

其本质是 db.session.query(模型类) 的快捷方式，无需显式操作 db.session。

代码示例，比如定义一个继承自 db.Model 的模型类 CommonModel：

from flask_sqlalchemy import SQLAlchemy  
db = SQLAlchemy()  # 初始化 SQLAlchemy 实例  # 定义模型类（继承自 db.Model）  
class CommonModel(db.Model):  id = db.Column(db.Integer, primary_key=True)  # 其他字段...  

以下两种写法等价

# 写法 1：通过模型类的 query 属性（隐式绑定会话）  
result1 = CommonModel.query.filter_by(field='value').first()  # 写法 2：通过 db.session 显式绑定模型类  
result2 = db.session.query(CommonModel).filter_by(field='value').first()  

---

2、基础查询

2.1、如何定义查询：设置过滤条件

2.1.1、get(primary_key)：按主键精准定位

• 作用：通过模型类的主键（如 id）直接定位单条记录，是主键查询的最优选择。
• 优势：直接利用数据库主键索引，查询效率最高。
• 示例（以 User 模型为例）：

  user = User.query.get(1)  # 查询 ID 为 1 的用户（存在返回实例，不存在返回 None）  
  

2.1.2、filter_by(**kwargs)：基于关键字的简单等值过滤

• 作用：通过模型类属性的等值条件（如 username='alice'）过滤记录。
• 限制：仅支持等值查询（=），无法处理范围（>, <）或模糊查询（LIKE）。
• 示例（以 User 模型为例）：

  active_users = User.query.filter_by(is_active=True).all()  # 查询所有活跃用户  
  

2.1.3、filter(条件表达式)：灵活的多条件查询

• 作用：支持范围、模糊、逻辑与/或等复杂条件，是 filter_by 的增强版。
• 语法：通过模型类属性构建表达式（如 User.age > 18）。
• 示例（以 User 模型为例）：

  from datetime import datetime  
  from sqlalchemy import or_  # 查询 2023 年后注册且邮箱以 'example.com' 结尾的用户（范围+模糊）  
  users = User.query.filter(  User.registered_at > datetime(2023, 1, 1),  User.email.like('%@example.com')  
  ).all()  # 查询年龄大于 18 或用户名含 'test' 的用户（逻辑或）  
  users = User.query.filter(  or_(User.age > 18, User.username.like('%test%'))  
  ).all()  
  

2.1.4、order_by(字段表达式)：按字段排序

• 作用：指定结果的排序规则（正序 / 倒序）。
• 语法：通过模型类属性指定排序字段（如 User.registered_at.desc() 倒序）。
• 示例：

# 按注册时间倒序（最新注册在前）  
recent_users = User.query.order_by(User.registered_at.desc()).all()  # 先按年龄正序，再按注册时间倒序（多字段排序）  
users = User.query.order_by(User.age.asc(), User.registered_at.desc()).all()  

2.1.5、with_entities(字段列表)：仅查询指定字段

• 作用：仅返回指定字段的数据（减少数据传输量）。
• 示例：

# 仅查询用户的 ID 和用户名  
user_ids = User.query.with_entities(User.id, User.username).all()  # 返回 [(1, 'alice'), (2, 'bob')...]  

2.2、如何获取结果：提取查询数据

定义查询条件后，需通过方法提取最终结果集（单条、多条、统计值或特定聚合值）。

2.2.1、first()：获取首条记录

• 作用：返回查询结果中的第一条记录（无结果返回 None）。
• 适用场景：已知查询结果最多一条（如用户登录验证）。
• 示例（以 User 模型为例）：

  user = User.query.filter_by(username='alice').first()  # 查找用户名为 'alice' 的用户（可能不存在）  
  

2.2.2、all()：获取所有符合条件的记录

• 作用：返回查询结果的所有记录（列表，无结果返回空列表 []）。
• 适用场景：需要批量处理数据（如展示用户列表）。
• 示例（以 User 模型为例）：

  users = User.query.filter(User.age > 18).all()  # 查找所有年龄大于 18 的用户（可能为空列表）  
  

2.2.3、one()：严格获取单条记录（无结果或多结果抛异常）

• 作用：要求查询结果必须恰好一条，否则抛出异常（NoResultFound 或 MultipleResultsFound）。
• 适用场景：业务逻辑要求结果唯一（如查询“当前生效的配置”）。
• 示例（以 Config 模型为例）：

  from sqlalchemy.exc import NoResultFound, MultipleResultsFound  try:  current_config = Config.query.filter_by(is_active=True).one()  
  except NoResultFound:  print("无生效配置！")  
  except MultipleResultsFound:  print("存在多个生效配置，需检查数据！")  
  

2.2.4、count()：统计结果数量

• 作用：直接执行 SELECT COUNT(*)，高效统计符合条件的记录总数。
• 优势：避免加载所有数据，性能优于 len(all())。
• 示例（以 User 模型为例）：

 # 统计活跃用户数量（返回整数）active_count = User.query.filter_by(is_active=True).count()    

2.2.5、limit(n)：限制返回数量

• 作用：仅返回前 n 条记录。
• 示例：

# 获取分数最高的前 5 个用户
top_5_users = User.query.order_by(User.score.desc()).limit(5).all()   

2.2.6、offset(n)：跳过前 n 条记录

• 作用：结合 limit 实现分页（如跳过前 10 条，取后 10 条）。
• 示例：

# 第 2 页数据（每页 10 条）
page_2_users = User.query.order_by(User.id).offset(10).limit(10).all()    

2.2.7、使用 paginate() 处理大数据分页

通过 paginate() 封装 offset 和 limit，自动处理分页逻辑，避免一次性加载大量数据：

# 获取第 2 页，每页 10 条数据（自动处理越界）  
page_obj = User.query.order_by(User.registered_at.desc()).paginate(page=2, per_page=10)  
current_users = page_obj.items  # 当前页数据  
total_pages = page_obj.pages  # 总页数  

---

3、关联查询：处理表间关系与预加载优化

在实际项目中，模型类间通常存在关联（如用户与帖子的一对多关系）。
通过 relationship 字段定义关联后，需结合预加载优化避免 N+1 查询问题。

3.1、模型类关联关系定义（以用户-帖子为例）

class Post(db.Model):  id = db.Column(db.Integer, primary_key=True)  title = db.Column(db.String(200))  author_id = db.Column(db.Integer, db.ForeignKey('user.id'))  # 外键关联用户 ID  class User(db.Model):  id = db.Column(db.Integer, primary_key=True)  username = db.Column(db.String(80))  # 定义一对多关系：user.posts 可获取用户所有帖子  posts = db.relationship('Post', backref='author', lazy='select')  # backref 为 post.author 提供反向引用  

• backref：在关联模型（如 Post）中自动创建反向引用（post.author 可获取用户实例）。
• lazy：控制关联数据的加载时机（默认 'select'，即访问时加载）。

3.2、预加载优化：避免 N+1 查询

直接访问关联数据（如 user.posts）时，SQLAlchemy 默认会触发多次查询（N+1 问题）。通过 joinedload 预加载，可一次性加载关联数据，减少数据库交互。

示例：未优化的 N+1 查询

# 查询 10 个用户，并获取他们的帖子（触发 1（用户查询） + 10（帖子查询）次 SQL）  
users = User.query.limit(10).all()  
for user in users:  print(user.posts)  # 每次循环触发一次帖子查询  

示例：优化后的预加载查询

from sqlalchemy.orm import joinedload  # 一次性加载用户及其帖子（仅 1 次 SQL）  
users = User.query.options(joinedload(User.posts)).limit(10).all()  
for user in users:  print(user.posts)  # 数据已预加载，无额外查询