如何自定义FastAPI分页模型：FastAPI-Pagination高级配置教程

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

FastAPI-Pagination是一款强大的FastAPI分页工具，它允许开发者轻松实现API的分页功能。本文将详细介绍如何通过FastAPI-Pagination的高级配置来自定义分页模型，满足不同项目的个性化需求。无论是修改默认参数、添加额外字段还是排除不需要的字段，本文都将为你提供简单实用的指导。

为什么需要自定义分页模型？

在实际开发中，不同的API接口可能需要不同的分页参数和返回格式。FastAPI-Pagination提供了灵活的自定义功能，让你可以根据项目需求调整分页行为。通过自定义分页模型，你可以：

• 修改默认的分页参数（如默认页面大小）
• 添加额外的返回字段
• 排除不需要的分页字段
• 自定义分页参数的验证规则

开始之前：安装FastAPI-Pagination

如果你还没有安装FastAPI-Pagination，可以通过以下命令进行安装：

pip install fastapi-pagination

如果你需要从源码安装，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/fa/fastapi-pagination
cd fastapi-pagination
pip install .

认识CustomizedPage：自定义分页的核心

FastAPI-Pagination的自定义功能主要通过CustomizedPage类实现。它的工作方式类似于typing.Annotated，但接受PageCustomizer协议的实例作为参数。你可以在fastapi_pagination/customization.py中找到相关实现。

下面是一个基本的自定义示例，将默认页面大小修改为100：

from typing import TypeVar
from fastapi import FastAPI, Query
from fastapi_pagination import Page, paginate, add_pagination
from fastapi_pagination.customization import CustomizedPage, UseParamsFields

app = FastAPI()
add_pagination(app)

T = TypeVar("T")

CustomPage = CustomizedPage[
    Page[T],
    UseParamsFields(
        size=Query(100, ge=1, le=1000),
    ),
]

@app.get("/nums")
async def get_nums() -> CustomPage[int]:
    return paginate(range(1_000))

实用自定义技巧

1. 添加额外字段

使用UseAdditionalFields可以为分页结果添加额外的字段。这在需要返回额外元数据时非常有用：

from typing import TypeVar
from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate
from fastapi_pagination.customization import CustomizedPage, UseAdditionalFields

app = FastAPI()
add_pagination(app)

T = TypeVar("T")

CustomPage = CustomizedPage[
    Page[T],
    UseAdditionalFields(
        user=str,
        is_admin=(bool, False),
    ),
]

@app.get("/nums")
async def get_nums(is_admin: bool = False) -> CustomPage[int]:
    return paginate(
        range(1_000),
        additional_data={
            "user": "Tony Stark",
            "is_admin": is_admin,
        }
    )

2. 排除不需要的字段

如果某些默认字段对你的API没有用处，可以使用UseExcludedFields将它们排除：

from typing import TypeVar
from fastapi import FastAPI
from fastapi_pagination import Page, add_pagination, paginate
from fastapi_pagination.customization import CustomizedPage, UseExcludedFields

app = FastAPI()
add_pagination(app)

T = TypeVar("T")

CustomPage = CustomizedPage[
    Page[T],
    UseExcludedFields("size", "page", "pages", "total"),
]

@app.get("/nums")
async def get_nums() -> CustomPage[int]:
    return paginate(range(1_000))

3. 自定义分页参数

使用UseParams可以完全自定义分页参数，包括参数名称、验证规则等。更多细节可以参考官方文档docs/customization/customizers/use_params.md。

自定义分页模型的实际效果

下面是一个自定义分页模型在Swagger UI中的展示效果，你可以看到分页参数和返回格式都根据我们的需求进行了定制：

组合使用多个自定义器

FastAPI-Pagination允许你同时使用多个自定义器，以满足更复杂的需求。例如，你可以同时修改参数字段和添加额外字段：

CustomPage = CustomizedPage[
    Page[T],
    UseParamsFields(size=Query(50, ge=10, le=200)),
    UseAdditionalFields(timestamp=datetime),
]

更多组合示例可以参考docs/customization/customizer_combinations.md。

总结

通过FastAPI-Pagination的自定义功能，你可以轻松调整分页行为以适应不同的项目需求。本文介绍了基本的自定义方法，包括修改参数、添加字段和排除字段等。要了解更多高级用法，可以查阅官方文档中的自定义部分。

希望这篇教程能帮助你更好地使用FastAPI-Pagination，构建出更加灵活和强大的API接口！

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