JSON 编解码:dart:convert、json_serializable、健壮错误处理
第 12 章 · JSON 编解码:dart:convert、json_serializable、健壮错误处理
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 基础
// 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):
1 → int, 1.0 → double, 1e3 → double
DateTime 可编码? false;Set 可编码? false
三个高频坑:
- Dart 会区分 int 和 double,Go 的
map[string]any全是float64。Go 程序员习惯"JSON 数字就是 float",在 Dart 里(json['age'] as int)遇到36.0会抛TypeError。稳妥写法:(json['age'] as num).toInt()。 jsonDecode返回的是Map<String, dynamic>,不是Map<String, Object?>。赋值给Object?没问题(dynamic可以赋给任何类型),但直接as Map<String, String>会失败——Map<String, dynamic>不是Map<String, String>的子类型。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 四个模型,覆盖真实项目里的全部形态。
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,多余的键自动被忽略——这通常是好事(服务端加字段不破坏老客户端)。
// 输入里有 "unknown_field": "会被忽略"
final User user = User.fromJson(...); // 正常解析
要"严格模式"(遇到未知字段就报错)得自己实现:
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()就是干这个的。不要在客户端默认开启——服务端先上线新字段、客户端还没更新是常态。
未知枚举值:必须降级
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。代码生成解决这个重复劳动:
dependencies:
json_annotation: ^4.9.0
dev_dependencies:
build_runner: ^2.4.0
json_serializable: ^6.8.0
// 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);
}
dart run build_runner build
# 产物:lib/src/models_generated.g.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) 让生成器两边都跳过它:
@JsonKey(includeFromJson: false, includeToJson: false)
final String localOnly;
// 输入里有 local_only 也不会被读入;toJson() 里也没有这个键
测试断言了这两个方向(test/json_test.dart 的"includeFromJson/includeToJson: false"用例)。
三个真实踩坑(本章示例都遇到了)
-
枚举绝不能带字段。最初写的是
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')+ 顶层映射函数才通过。 -
生成器不认识你忘了 import 的类型。
models_generated.dart里只show Address,用了Tier却没 import → 报同一个InvalidType。生成器是基于分析器的,类型必须先能解析。 -
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 定义了一套"断言 + 路径"的解码工具:
class JsonParseException implements Exception {
JsonParseException(this.path, this.message, [this.cause]);
final String path; // 如 '$.items[1].quantity'
final String message;
final Object? cause;
}
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})');
}
用它写解析器:
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'),
));
}
...
}
实测输出:
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) ← 路径精确到下标
入口统一兜住
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):
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。
优化清单(按收益排序):
- 减少数据量:分页、字段裁剪(
fields=id,name)、用gzip(http包会自动解压); - 别重复解析:解析一次存起来,不要在
build里jsonDecode; - 大响应丢 isolate:
Isolate.run(() => jsonDecode(raw)); - 避免中间 Map:超大数据用流式解析(
JsonUtf8Decoder/第三方json_stream),或改用二进制协议(protobuf/flatbuffers); const JsonEncoder.withIndent只用于调试,生产日志别美化输出(体积翻倍)。
12.7 运行与验证
cd examples/ch12-json
dart pub get
dart analyze # No issues found!
dart test # All tests passed! (24 个用例)
dart run
dart run 真实输出(节选):
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: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:没有运行期反射,用注解 + 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 老兵的三句话:
- JSON 是弱类型,Dart 是强类型——每一个字段都要显式决定"必需/可空/默认值/未知值怎么办"。
- 错误信息必须带路径(
$.items[1].quantity),否则线上日志等于没有。 - 代码生成不是魔法:枚举要纯、类型要能解析、非生成嵌套类要显式
toJson。这三个坑本章都踩过。
下一章把 JSON 接到网络上:http / dio、超时与重试、流式下载、错误分类,以及与 Riverpod 的 AsyncValue 集成——届时本章的解码层会成为网络层的最后一环。