跨平台开发 / 系统课时
用转换器处理特殊类型
用转换器处理特殊类型
接口里的 JSON 只能表达字符串、数字、布尔值、数组和对象,但业务模型常会使用 OrderId、金额值对象或自定义日期类型。JsonConverter 可以把“线上的 JSON 形态”和“代码里的 Dart 类型”隔开,让转换规则集中、可复用,也避免每个模型重复写 fromJson 与 toJson。
学习目标
- 理解
JsonConverter<DartType, JsonType>两个泛型参数分别代表什么 - 编写可复用的转换器,把 JSON 字符串映射为强类型 ID
- 在 Freezed 模型字段上应用转换器,并知道应把校验放在哪里
转换器解决的是边界翻译
假设接口返回订单 ID:
{
"id": "ORD-2026-0001"
}如果模型直接把它声明成 String,任意字符串都能被传入需要订单 ID 的代码。更清晰的做法是先定义 OrderId,再让转换器负责 JSON 边界上的字符串转换。JsonConverter<OrderId, String> 表示:Dart 侧类型是 OrderId,JSON 侧类型是 String。
编写可复用的 OrderIdConverter
下面的示例可以独立验证转换器本身;项目需已依赖 json_annotation。
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));
}预期输出:
ORD-2026-0001
ORD-2026-0001这里把格式校验放在转换边界:非法 JSON 会尽早失败,进入业务层的 OrderId 已满足最基本的格式要求。如果同一值对象还需要更复杂的业务规则,例如“订单是否存在”,应由领域或应用逻辑处理,而不是让 JSON 转换器访问数据库或网络。
接入 Freezed 模型
片段示例:下面代码依赖 freezed_annotation、json_annotation,并需要由 build_runner 生成 *.freezed.dart 与 *.g.dart。将转换器直接标注在字段上后,生成的 fromJson 和 toJson 会自动调用它。
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);
}生成代码后,可以用下面的调用验证双向转换行为:
final order = Order.fromJson({'id': 'ORD-2026-0001'});
print(order.id.runtimeType);
print(order.toJson()['id']);预期输出:
OrderId
ORD-2026-0001实际项目中可把 OrderId 与 OrderIdConverter 放在独立文件中,供多个请求和响应模型复用;金额、自定义日期、URI 等类型也可使用同样方式,只需明确 JSON 侧真实类型并保证正反转换一致。
设计转换器时要守住边界
转换器最好保持纯函数式:输入一个 JSON 值,返回 Dart 值;反向亦然。不要在其中读取全局状态、发请求或依赖当前时区,否则同一份 JSON 可能在不同环境得到不同结果。
对于金额,优先使用整数最小货币单位或明确的十进制定点类型,避免随意把金额字符串转成 double;对于日期,先确认后端格式和时区语义,再决定转换为 DateTime 还是自定义值对象。只要“线上的表示”和“代码里的类型”存在稳定映射,JsonConverter 就能把这层重复逻辑收拢到一个可测试的位置。