跨平台开发 / 系统课时
排查字段类型与空值异常
排查字段类型与空值异常
接口一旦出现 type 'String' is not a subtype of type 'num'、缺失键或转换器抛错,最重要的不是立刻把字段改成可空,而是把异常收敛到具体键,再判断问题来自 DTO 声明、后端响应还是兼容策略。下面用 Freezed 与 json_serializable 的生成代码建立一套可复现的定位路径。
学习目标
- 能从异常堆栈和
.g.dart反查出发生错误的 JSON 字段。 - 能区分类型漂移、缺失键、显式
null与自定义转换器异常。 - 能用最小测试验证修复,而不是通过放宽类型掩盖接口契约问题。
先把异常收敛到一个字段
序列化异常通常同时涉及三份证据:原始响应告诉你服务端实际发了什么,DTO 声明说明客户端期待什么,生成代码则暴露真正执行的强制转换或转换器调用。定位时不要先改模型,先保存触发异常的最小原始 JSON,并保留完整堆栈。
推荐按固定顺序处理:先找到堆栈中第一个属于当前模型 .g.dart 的位置,再查看这一行读取了哪个键;随后比较该键的实际运行时类型和 DTO 类型;最后再回到接口契约判断哪一边需要修正。

用严格字段和转换器暴露问题
下面的片段示例假设项目已经配置 freezed_annotation、json_annotation、freezed、json_serializable 与 build_runner。sku 是契约要求必传的字段,因此使用 required: true;price 允许兼容数字和旧版字符串;stock 可以缺失,所以声明为可空。
import 'package:freezed_annotation/freezed_annotation.dart';
part 'product_dto.freezed.dart';
part 'product_dto.g.dart';
double parsePrice(Object? value) {
if (value is num) {
return value.toDouble();
}
if (value is String) {
final parsed = double.tryParse(value);
if (parsed != null) {
return parsed;
}
}
throw FormatException('Invalid price: $value');
}
@freezed
abstract class ProductDto with _$ProductDto {
const factory ProductDto({
@JsonKey(required: true) required String sku,
@JsonKey(fromJson: parsePrice) required double price,
int? stock,
}) = _ProductDto;
factory ProductDto.fromJson(Map<String, dynamic> json) =>
_$ProductDtoFromJson(json);
}这段定义的关键不是“把所有异常都吞掉”,而是让每种异常对应明确的契约含义:缺少 sku 属于必填键违约;price 为数字或数字字符串属于兼容范围;price 变成对象、布尔值等未约定形态时仍然失败。
生成后的 product_dto.g.dart 片段通常会呈现类似下面的转换链;具体格式可能随生成器版本变化,但检查思路一致。
$checkKeys(
json,
requiredKeys: const ['sku'],
);
return _ProductDto(
sku: json['sku'] as String,
price: parsePrice(json['price']),
stock: (json['stock'] as num?)?.toInt(),
);看到 as String、as num? 或自定义函数调用后,就能把“某个模型解析失败”缩小为“某个键在某个转换点失败”。
用最小测试重现三类异常
把故障响应压缩成最小 fixture,比直接连接真实接口更容易确认边界。下面的测试分别覆盖旧版字符串价格、缺失必填键和转换器拒绝非法类型三种情况。
import 'package:flutter_test/flutter_test.dart';
import 'package:json_annotation/json_annotation.dart';
import '../lib/product_dto.dart';
void main() {
test('accepts legacy string price', () {
final dto = ProductDto.fromJson({
'sku': 'P-1',
'price': '19.90',
});
expect(dto.price, 19.9);
expect(dto.stock, isNull);
});
test('missing sku points to a contract breach', () {
expect(
() => ProductDto.fromJson({'price': 19.9}),
throwsA(isA<MissingRequiredKeysException>()),
);
});
test('invalid price triggers the converter', () {
expect(
() => ProductDto.fromJson({
'sku': 'P-3',
'price': {'value': 19.9},
}),
throwsA(isA<FormatException>()),
);
});
}运行测试:
flutter test test/product_dto_test.dart -r expanded预期输出中时间值会因机器而异:
<TIME> +1: accepts legacy string price
<TIME> +2: missing sku points to a contract breach
<TIME> +3: invalid price triggers the converter
<TIME> +3: All tests passed!如果第二个测试没有得到 MissingRequiredKeysException,先确认已重新运行代码生成;如果第三个测试没有进入 parsePrice,则应检查 @JsonKey(fromJson: parsePrice) 是否作用在正确字段。
根据证据决定修哪一层
常见现象可以直接映射到不同根因,不要把所有错误都归结为“JSON 不稳定”。
| 现象 | 优先检查 | 合理修复 |
|---|---|---|
String 不能转换为 num |
原始值是否真的从数字变成字符串 | 契约允许两种格式时加 converter;否则推动后端恢复类型 |
Null 不能转换为非空类型 |
键是缺失还是显式 null |
业务允许缺省才改为可空或补默认值 |
MissingRequiredKeysException |
必填键是否被服务端漏传 | 修后端或明确版本兼容策略 |
FormatException 来自 converter |
converter 是否覆盖了约定输入 | 扩充明确的兼容范围,不接受未知结构 |
判断标准是接口契约而不是“怎样能解析成功”。如果后端明确保证 sku 必传,就不应把它改成 String? 来绕过错误;如果历史版本确实把 price 同时发成数字和数字字符串,则 converter 是合理的兼容层,但最好在兼容期结束后收紧。
最后用同一份最小 fixture 重新执行生成和测试,并再对一次真实响应。修复后的目标不是“这次不崩”,而是异常能准确暴露真正违约的数据,同时合法的兼容输入仍然稳定通过。