FastAPI-Pagination项目教程：如何在路由中添加分页功能

FastAPI-Pagination项目教程：如何在路由中添加分页功能

【免费下载链接】fastapi-pagination 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-pagination

前言

在现代Web开发中，分页功能几乎是任何数据列表展示的必备特性。FastAPI-Pagination项目为FastAPI应用提供了简洁而强大的分页解决方案。本文将详细介绍如何在FastAPI路由中集成分页功能，涵盖多种常见使用场景。

基础分页实现

FastAPI-Pagination提供了最简单的分页集成方式，只需两个步骤：

1. 使用add_pagination函数注册分页功能到FastAPI应用
2. 在路由函数中使用Page作为返回类型注解或response_model

from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)

# 使用返回类型注解
@app.get("/items")
async def get_items() -> Page[int]:
    return paginate(range(100))

# 使用response_model
@app.get("/items-alt", response_model=Page[int])
async def get_items_alt():
    return paginate(range(100))

这两种方式都会自动处理page和size查询参数，例如：GET /items?page=2&size=10。

非Page类型的响应模型

有时我们可能需要返回非Page类型的响应，但仍想利用分页功能。这时可以使用set_page函数：

from typing import Annotated
from fastapi import FastAPI, Depends
from fastapi_pagination import Params, Page, paginate, set_page

app = FastAPI()

@app.get("/items-list")
async def get_items_list(params: Annotated[Params, Depends()]) -> list[int]:
    set_page(Page[int])
    page = paginate(range(100), params=params)
    return page.items

这种方式需要显式地声明和注入Params依赖，然后手动调用paginate函数。返回的page.items就是当前页的数据列表。

多分页模式支持

FastAPI-Pagination支持在同一路由处理函数中返回不同类型的分页响应，这在实际开发中非常有用：

from typing import Any
from fastapi import FastAPI
from fastapi_pagination import Page, LimitOffsetPage, add_pagination, paginate

app = FastAPI()
add_pagination(app)

@app.get("/page", response_model=Page[int])
@app.get("/limit-offset", response_model=LimitOffsetPage[int])
async def get_items() -> Any:
    return paginate(range(100))

这个例子展示了如何根据不同的端点返回不同类型的分页结果：

• /page端点使用基于页码的分页
• /limit-offset端点使用基于偏移量的分页

最佳实践建议

1. 一致性：在整个项目中保持统一的分页风格，要么全部使用类型注解，要么全部使用response_model

2. 性能考虑：对于大数据集，确保数据库查询是分页优化的，不要在内存中处理大量数据

3. 文档生成：使用类型注解或response_model可以确保OpenAPI文档正确生成分页参数

4. 错误处理：考虑添加自定义异常处理，为无效的分页参数提供友好的错误信息

总结

FastAPI-Pagination提供了灵活而强大的分页解决方案，支持多种使用场景。通过本文介绍的几种模式，开发者可以根据项目需求选择最适合的分页实现方式。无论是简单的分页需求，还是复杂的多分页模式，FastAPI-Pagination都能提供优雅的解决方案。

【免费下载链接】fastapi-pagination 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-pagination