跨平台开发 / 系统课时
按类型字段解析多态 JSON
按类型字段解析多态 JSON
当接口返回的对象结构由 type、kind 等字段决定时,普通单模型无法安全表达所有形态。本节用 Freezed 联合类型把判别字段映射到具体分支,并通过生成代码自动完成反序列化。
学习目标
- 配置 Freezed 联合类型使用服务端已有的判别字段
- 为每个 JSON 类型值绑定明确的联合分支
- 验证反序列化结果,并识别未知类型值等边界
先确定判别字段和值
假设消息接口固定返回 kind,其值决定其余字段结构:text 有 text,image 有尺寸和 URL,system 有系统事件码。这里的关键不是“字段可选”,而是同一个位置可能出现三种不同结构。

服务端字段名必须与 unionKey 一致;服务端值则要与各分支的联合值一致。不要为了迁就模型去改接口 JSON,模型应当对齐真实协议。
配置联合类型
下面示例保存为 lib/message_demo.dart。前提是项目已经加入 freezed_annotation,并在开发依赖中加入 freezed、json_serializable 与 build_runner。
import 'dart:convert';
import 'package:freezed_annotation/freezed_annotation.dart';
part 'message_demo.freezed.dart';
part 'message_demo.g.dart';
@Freezed(unionKey: 'kind')
sealed class Message with _$Message {
@FreezedUnionValue('text')
const factory Message.text({
required String id,
required String text,
}) = TextMessage;
@FreezedUnionValue('image')
const factory Message.image({
required String id,
required String url,
required int width,
required int height,
}) = ImageMessage;
@FreezedUnionValue('system')
const factory Message.system({
required String id,
required String code,
}) = SystemMessage;
factory Message.fromJson(Map<String, dynamic> json) =>
_$MessageFromJson(json);
}
void main() {
const source =
'{"kind":"image","id":"<ID>","url":"https://<HOST>/a.png","width":640,"height":480}';
final json = jsonDecode(source) as Map<String, dynamic>;
final message = Message.fromJson(json);
if (message case ImageMessage(:final id, :final width, :final height)) {
print('$id ${width}x$height');
}
}unionKey: 'kind' 告诉生成代码读取哪个字段;@FreezedUnionValue(...) 则把接口里的字符串值与具体 factory 绑定。这样业务代码得到的是 Message 的某个确定分支,而不是一组需要手工判断的可空字段。
生成代码并验证
先重新生成 Freezed 与 JSON 序列化代码。
dart run build_runner build --delete-conflicting-outputs预期结果:
生成或更新 lib/message_demo.freezed.dart 与 lib/message_demo.g.dart,命令正常结束,退出码为 0。再运行示例。
dart run lib/message_demo.dart预期输出:
<ID> 640x480实际构建日志中的耗时、步骤数量等动态信息可能不同;这里验证的是生成文件存在且示例能按 kind=image 进入图片分支。
处理协议边界
如果服务端使用 type,就把 unionKey 改为 type;如果类型值不是 factory 名的直接形式,可以继续用 @FreezedUnionValue 显式绑定。对外部接口而言,显式写出协议值通常比依赖命名转换更容易审查。
当 JSON 缺少判别字段、出现未声明的值,或者分支字段类型错误时,自动反序列化无法可靠选择并构造目标分支,应把它当作接口契约错误处理。若旧接口根本没有稳定的判别字段,而是只能靠“某字段是否存在”推断结构,则应改用自定义 JsonConverter,不要把这种猜测逻辑分散到页面代码中。