跨平台开发 / 系统课时

按类型字段解析多态 JSON

按类型字段解析多态 JSON

当接口返回的对象结构由 type、kind 等字段决定时,普通单模型无法安全表达所有形态。本节用 Freezed 联合类型把判别字段映射到具体分支,并通过生成代码自动完成反序列化。

学习目标

  • 配置 Freezed 联合类型使用服务端已有的判别字段
  • 为每个 JSON 类型值绑定明确的联合分支
  • 验证反序列化结果,并识别未知类型值等边界

先确定判别字段和值

假设消息接口固定返回 kind,其值决定其余字段结构:text 有 text,image 有尺寸和 URL,system 有系统事件码。这里的关键不是“字段可选”,而是同一个位置可能出现三种不同结构。

kind 字段选择 Freezed 联合分支的解析流程

服务端字段名必须与 unionKey 一致;服务端值则要与各分支的联合值一致。不要为了迁就模型去改接口 JSON,模型应当对齐真实协议。

配置联合类型

下面示例保存为 lib/message_demo.dart。前提是项目已经加入 freezed_annotation,并在开发依赖中加入 freezed、json_serializable 与 build_runner。

dart
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 序列化代码。

bash
dart run build_runner build --delete-conflicting-outputs

预期结果:

text
生成或更新 lib/message_demo.freezed.dart 与 lib/message_demo.g.dart,命令正常结束,退出码为 0。

再运行示例。

bash
dart run lib/message_demo.dart

预期输出:

text
<ID> 640x480

实际构建日志中的耗时、步骤数量等动态信息可能不同;这里验证的是生成文件存在且示例能按 kind=image 进入图片分支。

处理协议边界

如果服务端使用 type,就把 unionKey 改为 type;如果类型值不是 factory 名的直接形式,可以继续用 @FreezedUnionValue 显式绑定。对外部接口而言,显式写出协议值通常比依赖命名转换更容易审查。

当 JSON 缺少判别字段、出现未声明的值,或者分支字段类型错误时,自动反序列化无法可靠选择并构造目标分支,应把它当作接口契约错误处理。若旧接口根本没有稳定的判别字段,而是只能靠“某字段是否存在”推断结构,则应改用自定义 JsonConverter,不要把这种猜测逻辑分散到页面代码中。

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

目录与阅读设置

记录一个想法

按类型字段解析多态 JSON

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

登录哪都通