跨平台开发 / 系统课时
建模分页响应与元数据
建模分页响应与元数据
分页接口不只有 items,还可能携带 page、total、next_cursor 等元数据。若这些字段散落在请求函数和页面状态里,同一列表很快会出现多套判断。本节建立统一分页结果,让不同 API 的分页差异集中在解析边界。
学习目标
- 能把列表数据与分页元数据封装成可复用结果类型
- 能区分页码分页与游标分页的状态含义
- 能避免页面直接依赖接口里的分页字段名
先统一上层看到的分页形状
最稳定的外层通常只有两部分:items 保存当前批次数据,meta 保存“还能不能继续、下一次请求需要什么”这类分页信息。页码分页和游标分页不必强行拥有完全相同的字段,可以共享一个元数据抽象,再各自保存自己的参数。
这样做的关键不是追求一个万能 DTO,而是让页面只处理 PageResult<T>:渲染读取 items,加载更多读取 meta.hasMore,真正的 page、total 或 nextCursor 留在对应元数据类型中。
页码与游标不要混成一套算法
| 分页方式 | 常见字段 | 下一页依据 | 典型边界 |
|---|---|---|---|
| 页码分页 | page、page_size、total、items |
当前页码加一 | page * pageSize >= total 时结束 |
| 游标分页 | next_cursor、items |
服务端返回的下一游标 | next_cursor 为空时结束 |
cursor 通常是不透明令牌,客户端不应拆解、递增或自行构造。total 也不一定存在,尤其在大数据量或实时流式接口中,所以不要把“必须有总数”写进所有分页模型。
完整建模示例
下面示例同时解析页码分页和游标分页。两个接口结构不同,但最终都得到 PageResult<Product>,页面只需要读取统一的 items 与 meta.hasMore。
abstract class PageMeta {
const PageMeta();
bool get hasMore;
}
class NumberPageMeta extends PageMeta {
const NumberPageMeta({
required this.page,
required this.pageSize,
required this.total,
});
final int page;
final int pageSize;
final int total;
@override
bool get hasMore => page * pageSize < total;
}
class CursorPageMeta extends PageMeta {
const CursorPageMeta({required this.nextCursor});
final String? nextCursor;
@override
bool get hasMore => nextCursor != null && nextCursor!.isNotEmpty;
}
class PageResult<T> {
const PageResult({
required this.items,
required this.meta,
});
final List<T> items;
final PageMeta meta;
}
class Product {
const Product({required this.id, required this.name});
final String id;
final String name;
factory Product.fromJson(Map<String, dynamic> json) {
return Product(
id: json['id'] as String,
name: json['name'] as String,
);
}
}
List<Product> _parseProducts(Object? value) {
final list = value as List<dynamic>;
return list
.map((item) => Product.fromJson(item as Map<String, dynamic>))
.toList();
}
PageResult<Product> parseNumberPage(Map<String, dynamic> json) {
return PageResult(
items: _parseProducts(json['items']),
meta: NumberPageMeta(
page: json['page'] as int,
pageSize: json['page_size'] as int,
total: json['total'] as int,
),
);
}
PageResult<Product> parseCursorPage(Map<String, dynamic> json) {
return PageResult(
items: _parseProducts(json['data']),
meta: CursorPageMeta(
nextCursor: json['next_cursor'] as String?,
),
);
}
void main() {
final numberPage = parseNumberPage({
'page': 1,
'page_size': 2,
'total': 5,
'items': [
{'id': 'p-1', 'name': 'Keyboard'},
{'id': 'p-2', 'name': 'Mouse'},
],
});
final cursorPage = parseCursorPage({
'next_cursor': null,
'data': [
{'id': 'p-3', 'name': 'Monitor'},
],
});
print(
'number: ${numberPage.items.length} items, '
'hasMore=${numberPage.meta.hasMore}',
);
print(
'cursor: ${cursorPage.items.length} items, '
'hasMore=${cursorPage.meta.hasMore}',
);
}预期输出
number: 2 items, hasMore=true
cursor: 1 items, hasMore=false实际项目中,parseNumberPage 和 parseCursorPage 通常位于各自 DTO 或 Repository 的数据转换代码中。若使用 Freezed,可以让具体响应 DTO 负责 fromJson,再把它们转换为统一的 PageResult<T>。
元数据应该跟着结果走
页面状态不要分别保存 items、page、total、nextCursor 四五个变量,再靠业务代码维护它们的一致性。更稳妥的做法是把当前列表与最新分页元数据作为一个状态单元更新:请求成功后一次替换,刷新时一起重置,加载更多时根据元数据决定下一次参数。
处理不同接口的差异
接口字段名不同并不是页面应该关心的问题。某个服务返回 items,另一个返回 data;有的返回 total,有的只给 has_more。这些差异应在 DTO 或 Repository 中被转换成统一结构,而不是在 Widget 中增加 if 分支。
如果后端已经明确返回 has_more,优先使用后端语义,不必强行通过 total 推导。分页模型的目标是稳定表达“当前拿到了什么,以及下一步还能不能继续”,而不是把所有服务端字段原样复制到 UI 状态里。