9.5 分页
dbVisitor 的分页围绕两个核心类型：入参 PageObject 描述分页请求，出参 PageResult 承载分页结果。
入：创建分页请求
静态工厂（推荐）
Page page = PageObject.of(0, 20); // 第 0 页，每页 20 条，页码从 0 开始
Page oneBasedPage = PageObject.of(1, 20, 1); // 第 1 页，每页 20 条，页码从 1 开始
构造方法
PageObject page = new PageObject();
page.setPageSize(20); // 页大小（默认 0；请显式设置正数）
page.setCurrentPage(2); // 当前页码
page.setPageNumberOffset(1); // 页码偏移：设为 1 则第一页页码为 1
核心属性：
| 属性 | 说明 |
|---|---|
pageSize | 每页记录数，默认 0；分页查询应显式设置正数 |
currentPage | 当前页码 |
pageNumberOffset | 页码起始偏移。设为 1 则第一页页码为 1；默认 0 |
翻页方法：firstPage() / previousPage() / nextPage() / lastPage()。
出：读取分页结果
当 API 返回 PageResult<T> 时，可以读取分页统计信息：
PageResult<User> result = mapper.pageBySample(sample, pageInfo);
List<User> data = result.getData(); // 当前页数据
long total = result.getTotalCount(); // 总记录数
long pages = result.getTotalPage(); // 总页数
long position = result.getFirstRecordPosition(); // 第一条记录位置
通过 result.getData() 获取列表并遍历当前页数据。
在各 API 中使用
分页对象本身是通用的，但接入方式因 API 而异：
| API | 如何分页 | 返回类型 |
|---|---|---|
| 构造器 API | lambda.query(...).initPage(10, 0) 或 .usePage(page) | List<T> |
| BaseMapper | mapper.pageBySample(sample, page) | PageResult<T>（含统计） |
| 注解 Mapper | 方法签名加 Page 参数 | List<T> 或 PageResult<T> |
| Mapper 文件 | 方法签名加 Page 参数 | List<T> 或 PageResult<T> |
详细用法请参考各 API 的分页章节：
数据源差异
分页对象的用法不随数据库变化，但分页 SQL、总数 SQL 和执行边界由数据源决定：