跳到正文
CH 12工程化Dart11 分钟阅读

JSON 编解码:dart:convert、json_serializable、健壮错误处理

第 12 章 · JSON 编解码:dart:convert、json_serializable、健壮错误处理

本章示例examples/ch12-json在线阅读源码下载 zip

run

$cd examples/ch12-json && dart pub get && dart run

已验证

  • dart analyze 0 告警、dart test 24 个用例全绿
  • 完整工程已打包:打包下载
本章目录 · 17 节

本章与下一章(网络请求)是本教程的重点。JSON 是 Flutter 应用与后端的主要接口格式,也是最容易写出线上事故的地方:一个字段类型变了、少了一个字段、后端加了新枚举值,都可能让用户看到白屏。

12.1 本章目标

  • 掌握 jsonEncode / jsonDecode 的真实行为:返回什么类型、数字怎么分 int/double、什么不能编码;
  • 能手写健壮的 fromJson / toJson:嵌套、列表、可空、默认值、未知字段、未知枚举;
  • 会用 json_serializable 代码生成,知道 @JsonSerializable / @JsonKey 的常用开关;
  • 会写带路径的错误信息($.items[1].quantity),并区分语法错误与结构错误;
  • 知道大 JSON 的编解码成本,以及什么时候该丢进 isolate;
  • 建立 C/Go 对照:encoding/json 的 struct tag、cJSON 的手工遍历。

12.2 dart:convert 基础

dartlib/src/json_basics.dart源文件
// examples/ch12-json/lib/src/json_basics.dart
String encodeJson(Object? value) => jsonEncode(value);
Object? decodeJson(String raw) => jsonDecode(raw);

JSON 只有 6 种值,Dart 的映射是固定的:

JSON Dart(jsonDecode 的结果) Go(any) C(cJSON)
object Map<String, dynamic> map[string]any cJSON_Object
array List<dynamic> []any cJSON_Array
string String string cJSON_String
number(整数) int float64 double
number(小数/指数) double float64 double
boolean bool bool cJSON_True/False
null null nil cJSON_NULL

实测(dart run):

text
1 → int, 1.0 → double, 1e3 → double
DateTime 可编码? false;Set 可编码? false

三个高频坑:

  1. Dart 会区分 int 和 double,Go 的 map[string]any 全是 float64。Go 程序员习惯"JSON 数字就是 float",在 Dart 里 (json['age'] as int) 遇到 36.0 会抛 TypeError。稳妥写法:(json['age'] as num).toInt()。
  2. jsonDecode 返回的是 Map<String, dynamic>,不是 Map<String, Object?>。赋值给 Object? 没问题(dynamic 可以赋给任何类型),但直接 as Map<String, String> 会失败——Map<String, dynamic> 不是 Map<String, String> 的子类型。
  3. jsonEncode 不会替你转换任何类型:DateTime、Set、自定义对象都抛 JsonUnsupportedObjectError。Go 的 encoding/json 会帮你把 time.Time 编成 RFC3339,Dart 不会。

对照 C:cJSON 用 cJSON_Parse 建树,取值要 cJSON_GetObjectItem + cJSON_GetStringValue,最后必须 cJSON_Delete 释放整棵树。Dart 的 GC 替你做了释放,这是它比 C 舒服的地方;但"弱类型 + 强类型"的转换责任全在你身上。

12.3 手写模型:把弱类型变成强类型

examples/ch12-json/lib/src/models_manual.dart 里定义了 User / Address / Order / OrderItem 四个模型,覆盖真实项目里的全部形态。

dart
factory User.fromJson(Map<String, Object?> json) {
  final Object? rawTags = json['tags'];
  return User(
    id: json['id'] as String,
    email: json['email'] as String,
    name: json['name'] as String?,
    tier: tierFromWire(json['tier']),
    // 列表要逐个元素校验类型,不能直接 `as List<String>`
    tags: rawTags is List<Object?> ? rawTags.whereType<String>().toList() : const <String>[],
    address: json['address'] is Map<String, Object?>
        ? Address.fromJson(json['address']! as Map<String, Object?>)
        : null,
    createdAt: _parseDate(json['created_at']),
  );
}

四条要点

要点 写法 为什么
可空字段 json['name'] as String? 用 ? 让类型系统帮你检查
必需字段 json['id'] as String 缺失/类型错 → 抛 TypeError(边界层要兜)
数字 (json['quantity'] as num).toInt() JSON 可能给 1 或 1.0
列表 whereType<String>() 或逐元素判类型 as List<String> 对 List<dynamic> 会失败

未知字段:默认忽略

手写 fromJson 只取你关心的 key,多余的键自动被忽略——这通常是好事(服务端加字段不破坏老客户端)。

dart
// 输入里有 "unknown_field": "会被忽略"
final User user = User.fromJson(...);   // 正常解析

要"严格模式"(遇到未知字段就报错)得自己实现:

dart
const Set<String> _knownKeys = {'id', 'email', 'name', 'tags', 'tier', 'address', 'created_at'};
final List<String> unknown = json.keys.where((k) => !_knownKeys.contains(k)).toList();
if (unknown.isNotEmpty) throw JsonParseException(r'$', '未知字段: $unknown');

对照 Go:json.Decoder.DisallowUnknownFields() 就是干这个的。不要在客户端默认开启——服务端先上线新字段、客户端还没更新是常态。

未知枚举值:必须降级

dart
enum Tier {
  @JsonValue('free') free,
  @JsonValue('pro') pro,
}

Tier tierFromWire(Object? value) =>
    Tier.values.firstWhere((Tier t) => tierToWire(t) == value, orElse: () => Tier.free);

服务端加了 enterprise 等级,老客户端不认识——降级到默认值,而不是崩溃或显示空白。示例测试断言了这一点。

12.4 代码生成:json_serializable

手写 fromJson 一多就容易漏字段、hashCode、copyWith。代码生成解决这个重复劳动:

yaml
dependencies:
  json_annotation: ^4.9.0
dev_dependencies:
  build_runner: ^2.4.0
  json_serializable: ^6.8.0
dartlib/src/models_generated.dart源文件
// examples/ch12-json/lib/src/models_generated.dart
@JsonSerializable(fieldRename: FieldRename.snake)
class Account {
  Account({required this.id, required this.email, this.displayName, this.balanceCents = 0, ...});

  factory Account.fromJson(Map<String, Object?> json) => _$AccountFromJson(json);

  @JsonKey(name: 'display_name')
  final String? displayName;

  @JsonKey(defaultValue: 0)
  final int balanceCents;

  @JsonKey(unknownEnumValue: Tier.free)
  final Tier tier;

  @JsonKey(name: 'created_at', fromJson: _dateFromJson, toJson: _dateToJson)
  final DateTime? createdAt;

  /// 只在本机使用、不参与序列化的字段。
  /// 旧写法 `@JsonKey(ignore: true)` 已废弃,等价写法是下面这样。
  @JsonKey(includeFromJson: false, includeToJson: false)
  final String localOnly;

  Map<String, Object?> toJson() => _$AccountToJson(this);
}
bash
dart run build_runner build
# 产物:lib/src/models_generated.g.dart(要提交到版本库)

生成的代码长这样(节选,真实产物):

dart
Account _$AccountFromJson(Map<String, dynamic> json) => Account(
  id: json['id'] as String,
  email: json['email'] as String,
  displayName: json['display_name'] as String?,
  balanceCents: (json['balance_cents'] as num?)?.toInt() ?? 0,
  tags: (json['tags'] as List<dynamic>?)?.map((e) => e as String).toList() ?? const <String>[],
  address: json['address'] == null ? null : Address.fromJson(json['address'] as Map<String, dynamic>),
  tier: $enumDecodeNullable(_$TierEnumMap, json['tier'], unknownValue: Tier.free) ?? Tier.free,
  createdAt: Account._dateFromJson(json['created_at']),
  isActive: json['is_active'] as bool? ?? true,
);

常用开关

注解 作用
@JsonSerializable() 默认:字段名与 JSON key 一致
fieldRename: FieldRename.snake displayName → display_name
explicitToJson: true 嵌套对象在 toJson 里递归调用其 toJson
@JsonKey(name: 'x') 单字段重命名(优先于 fieldRename)
@JsonKey(defaultValue: 0) 缺失/null 时给默认值
@JsonKey(unknownEnumValue: Tier.free) 未知枚举值降级
@JsonKey(includeFromJson: false, includeToJson: false) 完全不参与序列化("忽略"字段)
@JsonKey(fromJson:, toJson:) 自定义转换(DateTime、枚举、嵌套手写模型)
@JsonValue('free') 枚举值的线上字符串
@JsonSerializable(disallowUnrecognizedKeys: true) 严格模式:未知 key 报错

第四个常被遗漏的开关:ignore

有些字段是"本机用的"(UI 状态、缓存、脱敏标记),根本不该出现在协议里。 @JsonKey(includeFromJson: false, includeToJson: false) 让生成器两边都跳过它:

dart
@JsonKey(includeFromJson: false, includeToJson: false)
final String localOnly;

// 输入里有 local_only 也不会被读入;toJson() 里也没有这个键

测试断言了这两个方向(test/json_test.dart 的"includeFromJson/includeToJson: false"用例)。

三个真实踩坑(本章示例都遇到了)

  1. 枚举绝不能带字段。最初写的是 enum Tier { free('free'), pro('pro'); final String wireName; ... },build_runner 直接报:

    text
    Could not generate `fromJson` code for `tier`.
    To support the type `InvalidType` ...
    

    因为 json_serializable 只认"纯枚举"。改成 @JsonValue('free') + 顶层映射函数才通过。

  2. 生成器不认识你忘了 import 的类型。models_generated.dart 里只 show Address,用了 Tier 却没 import → 报同一个 InvalidType。生成器是基于分析器的,类型必须先能解析。

  3. toJson 不会自动调用非注解类的 toJson。Address 是手写模型(没有 @JsonSerializable),生成代码里 'address': instance.address 直接把对象放进 Map,jsonEncode 时抛 JsonUnsupportedObjectError。必须显式:

    dart
    @JsonKey(toJson: _addressToJson)
    final Address? address;
    static Map<String, Object?>? _addressToJson(Address? v) => v?.toJson();
    

    (explicitToJson: true 只对同样是 @JsonSerializable 的嵌套类型生效。)

build_runner 新版本用 AOT 编译,--delete-conflicting-outputs 已被移除(会打印 warning)。直接 dart run build_runner build 就行。

12.5 健壮解码:错误必须带路径

examples/ch12-json/lib/src/decoding.dart 定义了一套"断言 + 路径"的解码工具:

dart
class JsonParseException implements Exception {
  JsonParseException(this.path, this.message, [this.cause]);
  final String path;       // 如 '$.items[1].quantity'
  final String message;
  final Object? cause;
}
dart
Map<String, Object?> expectObject(Object? value, String path) { ... }
String expectString(Object? value, String path) { ... }
int expectInt(Object? value, String path) {
  if (value is int) return value;
  // JSON 里 3.0 很常见,接受"值为整数的 double"
  if (value is double && value == value.truncateToDouble() && value.isFinite) return value.toInt();
  throw JsonParseException(path, '期望整数,实际是 $value (${value.runtimeType})');
}

用它写解析器:

dart
Order parseOrderStrict(Object? json) {
  final Map<String, Object?> map = expectObject(json, r'$');
  final String id = expectString(map['id'], r'$.id');

  final List<Object?> rawItems = expectList(map['items'], r'$.items');
  final List<OrderItem> items = <OrderItem>[];
  for (var i = 0; i < rawItems.length; i++) {
    final String path = '\$.items[$i]';
    final Map<String, Object?> item = expectObject(rawItems[i], path);
    items.add(OrderItem(
      sku: expectString(item['sku'], '$path.sku'),
      quantity: expectInt(item['quantity'], '$path.quantity'),
      unitCents: expectInt(item['unit_cents'], '$path.unit_cents'),
    ));
  }
  ...
}

实测输出:

text
JsonParseException($): JSON 语法错误: Unexpected character
JsonParseException($): 字段类型不匹配: type 'int' is not a subtype of type 'String' in type cast
JsonParseException($): 期望 object,实际是 List<dynamic>
JsonParseException($.items[1].quantity): 期望整数,实际是 1.5 (double)  ← 路径精确到下标

入口统一兜住

dart
T decodeModel<T>(String raw, T Function(Map<String, Object?> json) fromJson) {
  final Object? decoded;
  try {
    decoded = jsonDecode(raw);
  } on FormatException catch (e) {
    throw JsonParseException(r'$', 'JSON 语法错误: ${e.message}', e);
  }

  final Map<String, Object?> root = expectObject(decoded, r'$');
  try {
    return fromJson(root);
  } on JsonParseException {
    rethrow;
  } on TypeError catch (e) {
    throw JsonParseException(r'$', '字段类型不匹配: $e', e);
  }
}

为什么必须统一兜住:TypeError 是 Dart 的"程序错误",在 Flutter 里会进 FlutterError.onError,线上表现为红屏/白屏。边界层把它翻译成业务异常,UI 才能显示"数据格式错误,请稍后重试"。

对照:三种语言怎么报错

场景 Go C(cJSON) Dart
语法错误 json.Unmarshal 返回 *SyntaxError(带 Offset) cJSON_Parse 返回 NULL,用 cJSON_GetErrorPtr() jsonDecode 抛 FormatException(带 offset)
类型错误 struct tag 解码失败返回 *UnmarshalTypeError(带 Field/Offset) 你取的字段类型不对只能自己判断/UB as/expectXxx 抛 TypeError/自定义异常
未知字段 默认忽略,DisallowUnknownFields 可严格 无所谓,你只取想要的 默认忽略,需自己实现严格模式
缺字段 零值 返回 NULL 必需字段抛异常,可空字段为 null

12.6 大 JSON 的性能

dart run 的真实数据(20 000 行、1.81 MB):

text
fixture 大小: 1.81 MB
同步解码: 20000 行, 17ms
isolate 解码: 20000 行, 14ms(含 spawn 开销)
解码+重新编码: 33ms

怎么读这组数字:

  • 1.8MB / 17ms,约 100 MB/s,对 JSON 解析来说正常;
  • 17ms 已经超过一帧(16.6ms)——在 Flutter 里就是掉一帧;20k 行以上的响应应该丢进 isolate(Isolate.run,见 ch08);
  • isolate 这次只快一点,因为 spawn + 字符串复制(1.8MB)的开销占了大部分;对更大的数据、或连续解码多次时优势才明显。关键收益不是更快,而是不卡 UI。

优化清单(按收益排序):

  1. 减少数据量:分页、字段裁剪(fields=id,name)、用 gzip(http 包会自动解压);
  2. 别重复解析:解析一次存起来,不要在 build 里 jsonDecode;
  3. 大响应丢 isolate:Isolate.run(() => jsonDecode(raw));
  4. 避免中间 Map:超大数据用流式解析(JsonUtf8Decoder/第三方 json_stream),或改用二进制协议(protobuf/flatbuffers);
  5. const JsonEncoder.withIndent 只用于调试,生产日志别美化输出(体积翻倍)。

12.7 运行与验证

bash
cd examples/ch12-json
dart pub get
dart analyze          # No issues found!
dart test             # All tests passed! (24 个用例)
dart run

dart run 真实输出(节选):

text
1 → int, 1.0 → double, 1e3 → double
DateTime 可编码? false;Set 可编码? false

--- 2. 手写模型 ---
displayName=Ada Lovelace, tier=pro, city=London, createdAt=1815-12-10 00:00:00.000Z

--- 3. json_serializable 生成模型 ---
displayName=Grace, balance=0(默认值), tier=Tier.free(未知值降级), isActive=true(默认值)
Payload.toJson 里 address 已被递归序列化: true

--- 4. 错误处理 ---
JsonParseException($.items[1].quantity): 期望整数,实际是 1.5 (double)

--- 5. 性能 ---
fixture 大小: 1.81 MB
同步解码: 20000 行, 17ms
isolate 解码: 20000 行, 14ms(含 spawn 开销)

附:C/Go 代码对照:struct tag vs 代码生成

go
// Go:struct tag 描述映射,encoding/json 用反射填字段
type Account struct {
    ID           string  `json:"id"`
    DisplayName  *string `json:"display_name"`
    BalanceCents int     `json:"balance_cents"`
    IsActive     bool    `json:"is_active"`
}

var a Account
if err := json.Unmarshal(data, &a); err != nil {
    var typeErr *json.UnmarshalTypeError
    if errors.As(err, &typeErr) { /* 类型不匹配 */ }
}
dart
// Dart:没有运行期反射,用注解 + build_runner 生成同样的映射代码
@JsonSerializable(fieldRename: FieldRename.snake)
class Account {
  Account({required this.id, required this.email, this.displayName, this.balanceCents = 0});

  factory Account.fromJson(Map<String, Object?> json) => _$AccountFromJson(json);

  final String id;
  final String email;
  @JsonKey(name: 'display_name')
  final String? displayName;
  @JsonKey(defaultValue: 0)
  final int balanceCents;
}

Go 的字段名靠 tag,Dart 的字段名靠 fieldRename/@JsonKey;Go 的零值自动生效,Dart 必须显式写 defaultValue。

12.8 本章小结 + C/Go 对照清单

主题 Go C(cJSON) Dart 陷阱
编解码 encoding/json cJSON_Parse / cJSON_Print jsonEncode / jsonDecode 数字 int/double 的区分
字段映射 struct tag json:"name" 手动取字段(无反射) @JsonKey(name:) / fieldRename 枚举必须纯、依赖必须 import
未知字段 默认忽略(可严格) 天然忽略 默认忽略(需自己实现严格) 客户端别开严格模式
缺字段 零值 NULL 必需字段抛异常 / defaultValue 默认值要显式声明
嵌套对象 自动递归 手动递归 explicitToJson / @JsonKey(toJson:) 非生成类的 toJson 不自动调用
时间 time.Time(RFC3339) 字符串 + strptime 字符串 + DateTime.parse 时区:统一用 UTC
错误 error 返回值 NULL + 错误指针 异常(FormatException/TypeError) 边界层必须翻译成业务异常
大 JSON json.Decoder 流式 树式解析 jsonDecode 全量 + isolate 超过 16ms 就掉帧

给 C/Go 老兵的三句话:

  1. JSON 是弱类型,Dart 是强类型——每一个字段都要显式决定"必需/可空/默认值/未知值怎么办"。
  2. 错误信息必须带路径($.items[1].quantity),否则线上日志等于没有。
  3. 代码生成不是魔法:枚举要纯、类型要能解析、非生成嵌套类要显式 toJson。这三个坑本章都踩过。

下一章把 JSON 接到网络上:http / dio、超时与重试、流式下载、错误分类,以及与 Riverpod 的 AsyncValue 集成——届时本章的解码层会成为网络层的最后一环。