跨平台开发 / 系统课时
定义序列化失败错误
定义序列化失败错误
REST 请求即使拿到 200,也可能因为字段类型不匹配、必填字段缺失或自定义转换器抛错而无法生成模型。本节把这类失败单独归入数据层错误,让调用方能区分“请求没成功”和“响应契约无法解析”。
学习目标
- 区分网络、HTTP 状态码与 JSON 序列化失败
- 用统一异常包装
Freezed/json_serializable的解析错误 - 保留足够诊断信息,同时避免把完整响应体直接写入日志
先把失败边界分开
一次 REST 调用至少有三类失败:请求没有完成,例如超时或断网;服务端返回非预期状态码;状态码成功,但响应体无法转换为应用模型。第三类才属于序列化失败。
如果仓库层把三类问题都包装成同一个 Exception,上层只能显示“加载失败”,日志也无法判断应该检查网络、接口状态还是数据契约。更合适的做法是让 HTTP 客户端负责传输错误,让模型解码入口专门把解析错误转换为数据层错误。

打开 checked 转换
json_serializable 的 checked 选项会让生成代码在字段转换失败时补充模型和字段上下文,并抛出 CheckedFromJsonException。对于接收外部 API 的数据边界,这通常比直接得到一个缺少上下文的类型错误更容易定位。
build.yaml 可以统一开启该选项:
targets:
$default:
builders:
json_serializable:
options:
checked: true这是配置片段。重新运行项目现有的代码生成流程后,生成的 fromJson 会使用 checked 转换;验证时可向模型传入一个明显错误的字段类型,确认异常被包装为 CheckedFromJsonException。不同版本生成代码的具体文本可能不同,不应依赖生成文件的字符串内容做断言。
在数据边界统一转换异常
不要让页面层直接认识 CheckedFromJsonException、FormatException 或 TypeError。可以在仓库或远端数据源的解码入口把它们转换成稳定的数据层异常。
下面是片段示例,依赖项目中已经由 Freezed/json_serializable 生成的 UserDto.fromJson:
import 'package:json_annotation/json_annotation.dart';
final class SerializationFailure implements Exception {
const SerializationFailure({
required this.model,
required this.cause,
});
final String model;
final String cause;
@override
String toString() => 'SerializationFailure(model: $model, cause: $cause)';
}
T decodeModel<T>(
Map<String, dynamic> json,
T Function(Map<String, dynamic>) fromJson, {
required String modelName,
}) {
try {
return fromJson(json);
// 只转换已知的数据契约错误,避免掩盖程序缺陷。
} on CheckedFromJsonException catch (error) {
throw SerializationFailure(
model: modelName,
cause: error.toString(),
);
} on FormatException catch (error) {
throw SerializationFailure(
model: modelName,
cause: error.message,
);
} on TypeError catch (error) {
throw SerializationFailure(
model: modelName,
cause: error.toString(),
);
}
}
// 仓库或远端数据源只通过这一入口建立模型。
final user = decodeModel(
responseJson,
UserDto.fromJson,
modelName: 'UserDto',
);这段包装有两个关键点。第一,只捕获明确属于“数据无法按契约转换”的异常,不用 catch (Object) 把程序错误也伪装成接口脏数据。第二,向上层暴露稳定的 SerializationFailure,这样领域层或 UI 不需要依赖生成器实现细节。
缺字段和自定义转换器怎么归类
必填非空字段缺失,本质上是接口没有满足模型契约;字段类型错误,例如期望整数却收到对象,也属于同一类。自定义 JsonConverter 内主动抛出的 FormatException,通常也应该在数据边界转换为序列化失败,因为它表示原始值不能转成目标类型。
但不要把所有异常都归到这里。例如令牌过期通常由状态码或业务错误码表达,磁盘写入失败属于存储错误,程序中的 StateError 也不应该被无条件吞掉。错误类型越准确,重试、告警和用户提示才越可靠。
日志只保留可诊断信息
序列化错误日志建议记录模型名、接口标识、字段路径或异常摘要,以及请求关联 ID。不要默认打印完整响应体,因为其中可能包含令牌、手机号或其他敏感字段。
数据层最终应该做到:网络问题仍是网络问题,HTTP 失败仍是 HTTP 失败,而模型无法建立时得到明确的 SerializationFailure。这样上层既能采取不同处理策略,也能快速把问题定位到接口契约。