跨平台开发 / 系统课时
序列化枚举与未知值
序列化枚举与未知值
后端状态字段通常用字符串表示,但 Dart 代码更适合使用枚举。真正棘手的不是已知值,而是服务端先上线一个新状态时,旧版 App 会如何处理。本篇用 JsonValue 固定枚举映射,并用 unknownEnumValue 对未知值做兼容兜底,同时说明什么时候应该严格失败。
学习目标
- 为枚举建立明确、稳定的 JSON 字符串映射
- 使用
unknownEnumValue避免新增状态直接导致反序列化失败 - 区分严格失败与兼容回退,并为未知状态保留可观察性
显式映射不要依赖枚举名
接口可能返回 pending_payment,而 Dart 枚举希望使用 pendingPayment。此时应使用 JsonValue 声明线上的真实值,而不是依赖枚举成员名恰好与接口一致。
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 表示当输入字符串不在已知枚举映射里时,不抛出枚举解析异常,而是返回指定的兜底成员。
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);
}生成代码后,可用一个“客户端尚未认识”的状态验证行为:
final order = Order.fromJson({
'id': 'ORD-1001',
'status': 'refunding',
});
print(order.status == OrderStatus.unknown);
print(order.toJson()['status']);预期输出:
true
unknown第一行说明旧客户端没有因为 refunding 崩在反序列化阶段;第二行说明一旦重新序列化,这个未知原值已经被归一化成 unknown。如果业务要求原样保留服务端的新状态字符串,仅靠枚举兜底并不够,应额外保留原始字段或设计专门的包装类型。
严格失败与兼容回退怎么选
两种策略解决的问题不同:
| 策略 | 行为 | 更适合 |
|---|---|---|
| 不配置兜底 | 遇到未知值立即反序列化失败 | 未知状态意味着数据不可继续安全处理 |
配置 unknownEnumValue |
未知值映射到指定枚举成员 | 客户端需要向前兼容,且未知状态可以降级展示 |
例如“订单展示状态”通常可以降级为“状态更新中”,而“支付指令类型”若未知就可能影响资金操作,此时严格失败更安全。判断标准不是“能不能避免崩溃”,而是未知值出现后,继续执行是否仍然满足业务安全边界。
让 unknown 可观察而不是静默吞掉
兜底枚举解决的是兼容性,不应让协议变化变得不可见。业务代码检测到 OrderStatus.unknown 时,可以记录埋点、日志或错误上报,并在 UI 上采用保守文案,而不是假装它等同于某个旧状态。
void handleStatus(OrderStatus status) {
if (status == OrderStatus.unknown) {
print('Unexpected order status received');
return;
}
print('Known status: ${status.name}');
}预期输出(传入 OrderStatus.unknown):
Unexpected order status received如果服务端新增状态是正常演进路径,推荐“兼容回退 + 可观察”;如果未知值意味着无法保证正确性,则让解析失败并尽快暴露协议不一致。枚举设计的重点不是消灭异常,而是明确客户端面对未来值时应继续、降级还是停止。