跨平台开发 / 系统课时

处理未知多态分支

处理未知多态分支

服务端新增多态类型时,旧版客户端最危险的做法不是“不认识”,而是直接反序列化失败。本节用 Freezed 的 fallback 联合分支接住未知 type,同时保留足够的识别信息用于日志和监控,让兼容性降级可观察、可追踪,而不是静默吞错。

学习目标

  • 用 Freezed 的 fallbackUnion 为未知判别值提供明确兜底分支
  • 区分“继续运行”与“契约完全兼容”,避免 fallback 掩盖真实数据问题
  • 设计适合监控的原始字段保留策略,并验证未知类型是否被正确接住

未知分支解决的是什么问题

假设接口用 type 区分消息类型,当前客户端只认识 text 和 image。服务端以后增加 poll 时,如果模型只允许已知分支,旧客户端可能在解析整个响应时失败,甚至连列表中原本可展示的消息也一起丢失。

fallback 的作用是把“未知类型”从解析异常变成一个显式值。业务层可以选择显示通用占位、忽略该项,或上报监控,但不会把它误当成已知业务类型。

未知多态分支的解析与监控流程

用 Freezed 接住未知类型

下面是片段示例,依赖项目已经配置 freezed_annotation、json_annotation、freezed、json_serializable 和 build_runner,并完成代码生成。REST 边界统一调用 parseMessage(),这样既使用 Freezed 的 fallback,又能主动保存原始判别值。

dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'message.freezed.dart';
part 'message.g.dart';

@Freezed(unionKey: 'type', fallbackUnion: 'unknown')
sealed class Message with _$Message {
  const factory Message.text({
    required String id,
    required String text,
  }) = TextMessage;

  const factory Message.image({
    required String id,
    required String url,
  }) = ImageMessage;

  const factory Message.unknown({
    required String id,
    String? rawType,
    Map<String, dynamic>? metadata,
  }) = UnknownMessage;

  factory Message.fromJson(Map<String, dynamic> json) =>
      _$MessageFromJson(json);
}

Message parseMessage(Map<String, dynamic> json) {
  final type = json['type'] as String?;
  const knownTypes = {'text', 'image'};

  if (type == null || !knownTypes.contains(type)) {
    final metadata = json['metadata'];
    return Message.unknown(
      id: json['id'] as String,
      rawType: type,
      metadata: metadata is Map<String, dynamic> ? metadata : null,
    );
  }

  return Message.fromJson(json);
}

unionKey 指定判别字段为 type,fallbackUnion: 'unknown' 让生成的反序列化逻辑在遇到未知判别值时仍有兜底。额外的 parseMessage() 则在进入生成代码前读取原始 type,因为 fallback 本身不会自动把未知判别值复制到名为 rawType 的业务字段。

例如服务端返回一个新类型:

json
{
  "type": "poll",
  "id": "m-42",
  "question": "Which one?",
  "metadata": {
    "source": "beta"
  }
}

调用 parseMessage() 后会得到 UnknownMessage,其中 rawType 为 poll,metadata 被保留,而未声明的 question 不会进入模型。验证时可在单元测试中断言结果类型、rawType 与允许记录的元数据;如果 id 是接口公共包络保证存在的字段,也应覆盖缺失 id 时的失败测试。

不要把 fallback 变成无底洞

未知分支应该承担“兼容性缓冲”,而不是把任意 JSON 都视为合法。已知类型如果缺少必填字段、字段类型错误,仍应暴露解析失败;否则服务端把 text 错传成数字时,也可能被错误地当成可接受数据。

如果监控只需要判断“出现了新类型”,通常记录 rawType、稳定 ID、接口版本和少量非敏感元数据就足够。若确实需要保存完整原始 JSON,应在 API 边界额外包一层转换器,并明确脱敏、采样和存储周期,不要直接把可能含令牌、邮箱或业务隐私的 payload 全量写入日志。

什么时候采用 unknown 分支

适合使用 fallback 的场景,是服务端可能先于客户端发布新多态类型,而且旧客户端可以安全地对未知类型降级。例如动态内容卡片、通知类型、实验性组件等。对于支付状态、权限决策、风控结果这类不能模糊处理的契约,未知值通常应该阻断业务流程并上报,而不是继续执行。

判断标准很简单:如果“不理解这个新分支”仍能安全完成当前操作,就可以设计 unknown;如果错误解释会改变资金、权限或数据一致性,就应保持严格失败。

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

目录与阅读设置

记录一个想法

处理未知多态分支

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

登录哪都通