FastAPI-CRUD-Router 分页功能详解

FastAPI-CRUD-Router 分页功能详解

分页功能概述

在现代Web应用中，分页是处理大量数据的必备功能。FastAPI-CRUD-Router 提供了开箱即用的分页支持，让开发者能够轻松实现数据的分页查询功能。

核心分页参数

FastAPI-CRUD-Router 通过两个简单的查询参数实现分页功能：

1. skip (跳过数量)

   • 类型：整数
   • 作用：指定在返回结果前要跳过的记录数量
   • 示例：skip=50 表示跳过前50条记录

2. limit (限制数量)

   • 类型：整数
   • 作用：指定返回的最大记录数量
   • 示例：limit=25 表示最多返回25条记录

分页配置

设置最大分页限制

在实际应用中，为了防止客户端请求过多数据导致性能问题，通常需要设置每页返回的最大记录数。FastAPI-CRUD-Router 允许在创建路由时通过 paginate 参数进行配置：

from fastapi_crudrouter import CRUDRouter

router = CRUDRouter(
    schema=MyPydanticModel,
    paginate=25  # 设置每页最多返回25条记录
)

这种配置方式既保证了灵活性，又能有效防止客户端请求过多数据。

分页使用示例

Python 请求示例

import requests

response = requests.get(
    'http://localhost:5000/items',
    params={
        'skip': 50,  # 跳过前50条记录
        'limit': 25  # 返回最多25条记录
    }
)

cURL 请求示例

curl -X GET -G \
'http://localhost:5000/items' \
-d skip=50 \
-d limit=25

上述示例表示获取第三页的数据（假设每页25条记录），因为跳过了前50条记录（即前两页）。

分页计算逻辑

理解分页参数如何工作很重要：

• 页码计算：页码 = (skip / limit) + 1
• 下一页：增加 skip 值为当前 skip + limit
• 上一页：减少 skip 值为当前 skip - limit

例如，要获取第四页数据（每页25条）：

• skip = 75 (因为 3页 × 25条 = 75)
• limit = 25

参数验证

FastAPI-CRUD-Router 会自动验证分页参数，确保其有效性。以下情况会返回422状态码（验证错误）：

1. skip参数小于0
2. limit参数小于1
3. limit参数超过设置的最大值（如果配置了paginate参数）

验证错误示例

{
  "detail": {
    "detail": [
      {
        "loc": ["query", "skip"],
        "msg": "skip query parameter must be greater or equal to zero",
        "type": "type_error.integer"
      }
    ]
  }
}

最佳实践建议

1. 合理设置最大分页限制：根据实际业务需求和服务器性能，设置合适的paginate值
2. 前端配合：前端应用应该正确处理分页参数，避免请求不合理的数据范围
3. 性能考虑：对于大数据集，确保数据库查询有适当的索引支持分页操作
4. 用户体验：考虑在API响应中包含总记录数等元信息，方便前端显示分页控件

总结

FastAPI-CRUD-Router 的分页功能设计简洁而强大，通过skip和limit两个参数即可实现灵活的分页控制。自动化的参数验证和可配置的最大分页限制，使得开发者能够轻松构建出既安全又高效的API接口。