跨平台开发 / 系统课时

处理泛型响应包装

处理泛型响应包装

后端常把业务数据包在统一的 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 文件。

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(', ')}');
}

预期输出

text
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。

当多个接口只差业务数据类型时,统一响应壳与分页容器能显著减少重复模型;而具体业务模型的解析方式仍由调用点明确提供,类型关系也因此保持可检查、可组合。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

处理泛型响应包装

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通