跨平台开发 / 系统课时

序列化枚举与未知值

序列化枚举与未知值

后端状态字段通常用字符串表示,但 Dart 代码更适合使用枚举。真正棘手的不是已知值,而是服务端先上线一个新状态时,旧版 App 会如何处理。本篇用 JsonValue 固定枚举映射,并用 unknownEnumValue 对未知值做兼容兜底,同时说明什么时候应该严格失败。

学习目标

  • 为枚举建立明确、稳定的 JSON 字符串映射
  • 使用 unknownEnumValue 避免新增状态直接导致反序列化失败
  • 区分严格失败与兼容回退,并为未知状态保留可观察性

显式映射不要依赖枚举名

接口可能返回 pending_payment,而 Dart 枚举希望使用 pendingPayment。此时应使用 JsonValue 声明线上的真实值,而不是依赖枚举成员名恰好与接口一致。

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

enum OrderStatus {
  @JsonValue('pending_payment')
  pendingPayment,

  @JsonValue('paid')
  paid,

  @JsonValue('cancelled')
  cancelled,

  @JsonValue('unknown')
  unknown,
}

这类映射属于协议的一部分。即使以后为了代码可读性重命名枚举成员,只要 JsonValue 不变,JSON 协议就不会跟着被意外改写。

为新增状态设置兼容兜底

片段示例:下面模型依赖 Freezed 与 json_serializable 的生成代码。unknownEnumValue 表示当输入字符串不在已知枚举映射里时,不抛出枚举解析异常,而是返回指定的兜底成员。

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

part 'order.freezed.dart';
part 'order.g.dart';

@freezed
abstract class Order with _$Order {
  const factory Order({
    required String id,
    @JsonKey(unknownEnumValue: OrderStatus.unknown)
    required OrderStatus status,
  }) = _Order;

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

生成代码后,可用一个“客户端尚未认识”的状态验证行为:

dart
final order = Order.fromJson({
  'id': 'ORD-1001',
  'status': 'refunding',
});

print(order.status == OrderStatus.unknown);
print(order.toJson()['status']);

预期输出:

text
true
unknown

第一行说明旧客户端没有因为 refunding 崩在反序列化阶段;第二行说明一旦重新序列化,这个未知原值已经被归一化成 unknown。如果业务要求原样保留服务端的新状态字符串,仅靠枚举兜底并不够,应额外保留原始字段或设计专门的包装类型。

严格失败与兼容回退怎么选

两种策略解决的问题不同:

策略 行为 更适合
不配置兜底 遇到未知值立即反序列化失败 未知状态意味着数据不可继续安全处理
配置 unknownEnumValue 未知值映射到指定枚举成员 客户端需要向前兼容,且未知状态可以降级展示

例如“订单展示状态”通常可以降级为“状态更新中”,而“支付指令类型”若未知就可能影响资金操作,此时严格失败更安全。判断标准不是“能不能避免崩溃”,而是未知值出现后,继续执行是否仍然满足业务安全边界。

让 unknown 可观察而不是静默吞掉

兜底枚举解决的是兼容性,不应让协议变化变得不可见。业务代码检测到 OrderStatus.unknown 时,可以记录埋点、日志或错误上报,并在 UI 上采用保守文案,而不是假装它等同于某个旧状态。

dart
void handleStatus(OrderStatus status) {
  if (status == OrderStatus.unknown) {
    print('Unexpected order status received');
    return;
  }

  print('Known status: ${status.name}');
}

预期输出(传入 OrderStatus.unknown):

text
Unexpected order status received

如果服务端新增状态是正常演进路径,推荐“兼容回退 + 可观察”;如果未知值意味着无法保证正确性,则让解析失败并尽快暴露协议不一致。枚举设计的重点不是消灭异常,而是明确客户端面对未来值时应继续、降级还是停止。

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

目录与阅读设置

阅读设置

17

记录一个想法

序列化枚举与未知值

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

登录哪都通