FastAPI-Pagination项目中的Items Transformer使用指南-CSDN博客

FastAPI-Pagination项目中的Items Transformer使用指南

什么是Items Transformer

在FastAPI-Pagination项目中，Items Transformer是一个强大的功能组件，它允许开发者在分页数据返回给客户端之前对数据进行转换处理。这种机制为数据格式化、字段补充或业务逻辑处理提供了极大的灵活性。

核心作用

Items Transformer本质上是一个处理函数，它接收原始数据项列表作为输入，经过处理后返回一个新的数据项列表。这种设计模式在以下场景中特别有用：

数据格式化：将数据库原始数据转换为前端需要的格式
字段补充：为每个数据项添加额外计算字段
数据过滤：移除或修改某些敏感字段
业务逻辑处理：对数据进行业务相关的转换

基本使用方式

最简单的使用方式是在调用paginate函数时直接传入一个transformer函数：

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

app = FastAPI()
add_pagination(app)

@app.get("/ints")
async def route() -> Page[int]:
    return paginate(
        range(100),
        transformer=lambda items: [item * 2 for item in items],  # 将每个元素乘以2
    )

在这个例子中，我们创建了一个简单的FastAPI路由，返回分页的整数列表。通过transformer参数，我们传入了一个lambda函数，将所有元素值翻倍。

全局配置方式

如果多个路由需要使用相同的转换逻辑，可以设置全局的Items Transformer：

from fastapi_pagination.api import set_items_transformer

# 设置全局转换器
set_items_transformer(lambda items: [item * 2 for item in items])

@app.get("/ints")
async def route() -> Page[int]:
    return paginate(range(100))  # 自动应用全局转换器

@app.get("/another-ints")
async def another_route() -> Page[int]:
    return paginate(range(100))  # 同样应用全局转换器

这种方式适合需要在多个端点保持统一数据转换逻辑的场景。

路由级配置

也可以为特定路由设置独立的Items Transformer：

@app.get("/ints")
async def route() -> Page[int]:
    set_items_transformer(lambda items: [item * 2 for item in items])
    return paginate(range(100))

@app.get("/ints-no-transformer")
async def another_route() -> Page[int]:
    return paginate(range(100))  # 不使用转换器

这种方式的优先级高于全局配置，允许开发者为特定路由定制转换逻辑。

异步Transformer处理

当使用异步分页函数时，transformer也可以是异步的：

from fastapi_pagination.async_paginator import paginate

async def transformer(items: list[int]) -> list[int]:
    # 模拟异步操作
    return [item * 2 for item in items]

@app.get("/ints")
async def route() -> Page[int]:
    return await paginate(range(100), transformer=transformer)

这在需要执行数据库查询或网络请求等异步操作时特别有用。