跨平台开发 / 系统课时
处理泛型响应包装
处理泛型响应包装
后端常把业务数据包在统一的 code、message、data 外壳里,分页接口又会继续嵌套列表与总数。若为每个接口复制一套响应模型,结构会迅速重复。本节用 Freezed 的泛型工厂把具体类型的解析函数显式传入,让同一套 ApiResponse<T> 和 Page<T> 安全复用。
学习目标
- 理解泛型 JSON 解析为什么需要显式提供
T的反序列化函数 - 使用
genericArgumentFactories定义可复用的响应壳与分页容器 - 正确组合
ApiResponse<Page<User>>这类多层泛型解析
为什么泛型不能自动知道怎么解析
json_serializable 能根据静态字段类型生成普通模型的解析代码,但生成 ApiResponse<T> 时并不知道运行时的 T 究竟是 User、Order 还是 Page<User>。因此,Freezed 的泛型 JSON 方案要求开启 genericArgumentFactories,并让 fromJson 接收一个 T Function(Object?) 回调。当前 Freezed 文档仍采用这一模式。([Dart packages][1])
解析时,外层模型只负责读取自己的字段;遇到 data,就调用方传进来的 fromJsonT。如果 T 本身还是泛型容器,再继续向下一层传入解析函数即可。

定义并运行可复用模型
下面给出一个可直接放入 lib/api_models.dart 的完整示例。它假设项目已安装 freezed_annotation、freezed、json_serializable 与 build_runner;先按项目既有代码生成流程生成 .freezed.dart 和 .g.dart 文件,再运行这个 Dart 文件。
import 'dart:convert';
import 'package:freezed_annotation/freezed_annotation.dart';
part 'api_models.freezed.dart';
part 'api_models.g.dart';
@freezed
abstract class User with _$User {
const factory User({
required int id,
required String name,
}) = _User;
factory User.fromJson(Map<String, dynamic> json) =>
_$UserFromJson(json);
}
@Freezed(genericArgumentFactories: true)
abstract class Page<T> with _$Page<T> {
const factory Page({
required List<T> items,
required int total,
}) = _Page<T>;
factory Page.fromJson(
Map<String, dynamic> json,
T Function(Object?) fromJsonT,
) =>
_$PageFromJson(json, fromJsonT);
}
@Freezed(genericArgumentFactories: true)
abstract class ApiResponse<T> with _$ApiResponse<T> {
const factory ApiResponse({
required int code,
required String message,
required T data,
}) = _ApiResponse<T>;
factory ApiResponse.fromJson(
Map<String, dynamic> json,
T Function(Object?) fromJsonT,
) =>
_$ApiResponseFromJson(json, fromJsonT);
}
void main() {
const raw = '''
{
"code": 0,
"message": "ok",
"data": {
"items": [
{"id": 1, "name": "Ada"},
{"id": 2, "name": "Lin"}
],
"total": 2
}
}
''';
final json = jsonDecode(raw) as Map<String, dynamic>;
final response = ApiResponse<Page<User>>.fromJson(
json,
(value) => Page<User>.fromJson(
value! as Map<String, dynamic>,
(item) => User.fromJson(item! as Map<String, dynamic>),
),
);
print('code=${response.code}');
print('total=${response.data.total}');
print('names=${response.data.items.map((e) => e.name).join(', ')}');
}预期输出
code=0
total=2
names=Ada, Lin生成器不会尝试推断 T,而是在生成的 fromJson 中保留回调参数,并在读取泛型字段时调用它。外层的 T 是 Page<User>,所以外层回调先构造分页对象;分页容器内部再用第二个回调把列表元素转成 User。
示例中的两个 value! 都建立在接口契约保证对应 JSON 值非空的前提上。如果后端允许 data 或列表元素为 null,模型类型就应改成可空,并在回调中显式处理,而不是依赖强制解包。
分页容器为什么也要泛型工厂
只给 ApiResponse<T> 开启泛型工厂还不够。因为当 T 是 Page<User> 时,Page 自己仍然包含未知的 T,它也必须知道如何把 items 中的每个元素转成 User。这就是多层泛型需要逐层传递解析函数的原因。
一个常见错误是把 User.fromJson 直接传给 ApiResponse<Page<User>>.fromJson。外层回调实际收到的是整个分页对象,而不是单条用户记录,因此类型与 JSON 结构都不匹配。判断回调应该解析什么时,只看当前这一层的 T:外层是 Page<User>,内层才是 User。
当多个接口只差业务数据类型时,统一响应壳与分页容器能显著减少重复模型;而具体业务模型的解析方式仍由调用点明确提供,类型关系也因此保持可检查、可组合。