---
url: /fastapi_best_architecture_docs/backend/reference/pagination.md
---
fba 基于 `fastapi-pagination` 封装了统一分页能力，核心实现位于 `backend/common/pagination.py`

## 普通分页

普通分页适用于后台管理中常见的列表页。接口层添加 `DependsPagination`，返回类型使用 `ResponseSchemaModel[PageData[XxxDetail]]`

```python
from backend.common.pagination import DependsPagination, PageData
from backend.common.response.response_schema import ResponseSchemaModel, response_base
from backend.database.db import CurrentSession


@router.get(
    '',
    summary='分页获取用户',
    dependencies=[
        DependsPagination,
    ],
)
async def get_users_paginated(
    db: CurrentSession,
) -> ResponseSchemaModel[PageData[GetUserInfoWithRelationDetail]]:
    page_data = await user_service.get_list(db=db)
    return response_base.success(data=page_data)
```

`DependsPagination` 默认提供以下查询参数：

| 参数   | 默认值 | 说明        |
|------|-----|-----------|
| page | 1   | 页码，最小为 1 |
| size | 20  | 每页数量，最大 200 |

返回数据包含：

| 字段          | 说明      |
|-------------|---------|
| items       | 当前页数据列表 |
| total       | 数据总条数  |
| page        | 当前页码   |
| size        | 每页数量   |
| total\_pages | 总页数    |
| links       | 分页链接   |

## Service / CRUD

Service 层通常调用 CRUD 层获取 SQLAlchemy `Select` 对象，再通过 `paging_data()` 生成分页数据

```python
from typing import Any

from sqlalchemy.ext.asyncio import AsyncSession

from backend.app.admin.crud.crud_user import user_dao
from backend.common.pagination import paging_data


class UserService:
    """用户服务类"""

    @staticmethod
    async def get_list(*, db: AsyncSession) -> dict[str, Any]:
        user_select = await user_dao.get_select(dept=None, username=None, phone=None, status=None)
        return await paging_data(db, user_select)
```

## 游标分页

游标分页适用于无限滚动、会话列表等需要基于游标继续加载的场景。接口层使用 `DependsCursorPagination`，返回类型使用
`ResponseSchemaModel[CursorPageData[XxxDetail]]`

```python
from backend.common.pagination import CursorPageData, DependsCursorPagination
from backend.common.response.response_schema import ResponseSchemaModel, response_base
from backend.database.db import CurrentSession


@router.get(
    '',
    summary='游标分页获取会话',
    dependencies=[
        DependsCursorPagination,
    ],
)
async def get_conversations(
    db: CurrentSession,
) -> ResponseSchemaModel[CursorPageData[GetAIConversationListDetail]]:
    page_data = await conversation_service.get_list(db=db)
    return response_base.success(data=page_data)
```

游标分页返回数据包含：

| 字段          | 说明       |
|-------------|----------|
| items       | 当前页数据列表  |
| next\_cursor | 下一页游标    |
| has\_more    | 是否还有更多数据 |