跨平台开发 / 系统课时

用转换器处理特殊类型

用转换器处理特殊类型

接口里的 JSON 只能表达字符串、数字、布尔值、数组和对象,但业务模型常会使用 OrderId、金额值对象或自定义日期类型。JsonConverter 可以把“线上的 JSON 形态”和“代码里的 Dart 类型”隔开,让转换规则集中、可复用,也避免每个模型重复写 fromJson 与 toJson。

学习目标

  • 理解 JsonConverter<DartType, JsonType> 两个泛型参数分别代表什么
  • 编写可复用的转换器,把 JSON 字符串映射为强类型 ID
  • 在 Freezed 模型字段上应用转换器,并知道应把校验放在哪里

转换器解决的是边界翻译

假设接口返回订单 ID:

json
{
  "id": "ORD-2026-0001"
}

如果模型直接把它声明成 String,任意字符串都能被传入需要订单 ID 的代码。更清晰的做法是先定义 OrderId,再让转换器负责 JSON 边界上的字符串转换。JsonConverter<OrderId, String> 表示:Dart 侧类型是 OrderId,JSON 侧类型是 String。

编写可复用的 OrderIdConverter

下面的示例可以独立验证转换器本身;项目需已依赖 json_annotation。

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

class OrderId {
  final String value;

  const OrderId(this.value);

  @override
  String toString() => value;
}

class OrderIdConverter implements JsonConverter<OrderId, String> {
  const OrderIdConverter();

  @override
  OrderId fromJson(String json) {
    if (!json.startsWith('ORD-')) {
      throw FormatException('Invalid order id: $json');
    }
    return OrderId(json);
  }

  @override
  String toJson(OrderId object) => object.value;
}

void main() {
  const converter = OrderIdConverter();

  final id = converter.fromJson('ORD-2026-0001');
  print(id);
  print(converter.toJson(id));
}

预期输出:

text
ORD-2026-0001
ORD-2026-0001

这里把格式校验放在转换边界:非法 JSON 会尽早失败,进入业务层的 OrderId 已满足最基本的格式要求。如果同一值对象还需要更复杂的业务规则,例如“订单是否存在”,应由领域或应用逻辑处理,而不是让 JSON 转换器访问数据库或网络。

接入 Freezed 模型

片段示例:下面代码依赖 freezed_annotation、json_annotation,并需要由 build_runner 生成 *.freezed.dart 与 *.g.dart。将转换器直接标注在字段上后,生成的 fromJson 和 toJson 会自动调用它。

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({
    @OrderIdConverter() required OrderId id,
  }) = _Order;

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

生成代码后,可以用下面的调用验证双向转换行为:

dart
final order = Order.fromJson({'id': 'ORD-2026-0001'});

print(order.id.runtimeType);
print(order.toJson()['id']);

预期输出:

text
OrderId
ORD-2026-0001

实际项目中可把 OrderId 与 OrderIdConverter 放在独立文件中,供多个请求和响应模型复用;金额、自定义日期、URI 等类型也可使用同样方式,只需明确 JSON 侧真实类型并保证正反转换一致。

设计转换器时要守住边界

转换器最好保持纯函数式:输入一个 JSON 值,返回 Dart 值;反向亦然。不要在其中读取全局状态、发请求或依赖当前时区,否则同一份 JSON 可能在不同环境得到不同结果。

对于金额,优先使用整数最小货币单位或明确的十进制定点类型,避免随意把金额字符串转成 double;对于日期,先确认后端格式和时区语义,再决定转换为 DateTime 还是自定义值对象。只要“线上的表示”和“代码里的类型”存在稳定映射,JsonConverter 就能把这层重复逻辑收拢到一个可测试的位置。

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

目录与阅读设置

记录一个想法

用转换器处理特殊类型

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

登录哪都通