Tortoise ORM（一个异步Python ORM）的典型分页查询实现

这段代码展示了使用Tortoise ORM（一个异步Python ORM）的典型分页查询实现。以下是对各部分的详细分析：

1. list 函数核心分析

定义：

async def list(self, page: int, page_size: int, search: Q = Q(), order: list = []) -> Tuple[Total, List[ModelType]]

关键点：

• 异步支持：通过 async 关键字支持异步操作

• 分页参数：page 和 page_size 控制分页逻辑

• 过滤条件：search 参数接收 Q 对象，支持复杂查询组合

• 排序控制：order 参数接收字段排序规则列表

• 返回值：总记录数和分页后的模型实例列表

工作流程：

1. 构建基础查询：query = self.model.filter(search)

2. 并发执行两个操作：

   • await query.count()：计算总记录数

   • await query.offset(...).limit(...).order_by(...)：获取分页结果

2. Tortoise ORM 核心方法分析

(1) count() 方法

def count(self) -> "CountQuery":

• 功能：返回查询集的对象总数

• 实现机制：构建特殊的 CountQuery 对象，执行 SELECT COUNT(*)

• 特点：延迟执行，需配合 await 使用

• 示例：

total = await Model.filter(name="test").count()

(2) offset(offset) 方法

def offset(self, offset: int) -> "QuerySet[MODEL]":

• 功能：设置查询结果的偏移量

• 参数校验：确保 offset ≥ 0

• 自动修正：当数据库需要显式LIMIT时，自动添加大值限制

• 示例：

results = await Model.offset(10).limit(20)

(3) limit(limit) 方法

def limit(self, limit: int) -> "QuerySet[MODEL]":

• 功能：限制查询结果的最大数量

• 参数校验：确保 limit ≥ 0

• 实现：设置查询集的 _limit 属性

• 示例：

results = await Model.limit(100)

(4) order_by(*orderings) 方法

def order_by(self, *orderings: str) -> "QuerySet[MODEL]":

• 功能：指定排序规则

• 参数格式：

  • 升序：'field_name'

  • 降序：'-field_name'

  • 支持关联表：'relation__field'

• 错误处理：当字段不存在时抛出 FieldError

• 示例：

results = await Model.order_by('created_at', '-name')

3. 分页逻辑实现原理

计算公式：

offset = (page - 1) * page_size

执行顺序：

1. 构建基础查询集：self.model.filter(search)

2. 并发执行：

   • count()：计算总记录数

   • 分页查询：offset(...).limit(...).order_by(...)

3. 返回组合结果

性能优化：

• 使用 await 并发执行计数和数据查询

• 避免多次构建查询对象

4. 示例使用场景

# 获取第2页，每页10条，按创建时间降序排列
page = 2
page_size = 10
search = Q(name__icontains="test")
order = ["-created_at"]

total, items = await Model.list(page, page_size, search, order)

5. 关键注意事项

1. 异步支持：所有数据库操作必须使用 await

2. 错误处理：

   • 参数错误：ParamsError（如负数偏移）

   • 字段错误：FieldError（无效排序字段）

3. 性能优化：

   • 避免大范围 LIMIT（如默认100万条）

   • 使用索引字段排序

6. 与其他ORM对比

总结：这段代码展示了Tortoise ORM的链式查询和分页功能，通过组合使用filter、count、offset、limit和order_by方法，实现了高效的分页查询。异步支持使其特别适合高并发场景，而链式调用提高了代码的可读性和复用性。