跨平台开发 / 系统课时
隔离部分失真的接口数据
隔离部分失真的接口数据
真实接口常出现“主体可用、局部字段脏掉”的情况,例如可选日期格式异常、某个子对象结构改变,或列表里只有一条记录损坏。本节建立分级处理策略,在保证关键契约不被掩盖的前提下,让可恢复的数据继续进入应用。
学习目标
- 判断何时应该整条响应失败,何时可以字段降级或过滤局部记录
- 为可选脏字段编写边界明确的兼容转换
- 在降级后保留监控信号,避免兼容逻辑长期掩盖接口回归
先按契约重要性决定策略
处理脏数据前先问两个问题:这个字段是否决定对象身份或业务正确性;丢失它之后,应用是否还能明确地解释这条数据。id、金额、权限状态等关键字段通常不适合静默降级,而头像地址、可选备注、非关键展示时间则可能允许回退为 null。
常见策略可以分成三类:关键字段异常时让整条对象失败;可选字段异常时回退到安全值;列表中的独立元素异常时过滤该元素,但必须记录被过滤的位置和数量。

可选字段只在边界内降级
下面的 Freezed 模型把 publishedAt 定义为可选展示字段。与其在转换器里悄悄吞掉错误,这里先规范化原始 JSON:只有该字段异常时才回退为 null,同时把降级字段返回给调用方;id 与 title 仍保持严格非空类型。
这是片段示例,依赖 Freezed/json_serializable 的生成文件:
import 'package:freezed_annotation/freezed_annotation.dart';
part 'article_dto.freezed.dart';
part 'article_dto.g.dart';
@freezed
class ArticleDto with _$ArticleDto {
const factory ArticleDto({
required String id,
required String title,
DateTime? publishedAt,
}) = _ArticleDto;
factory ArticleDto.fromJson(Map<String, dynamic> json) =>
_$ArticleDtoFromJson(json);
}
final class ArticleDecode {
const ArticleDecode({
required this.article,
required this.degradedFields,
});
final ArticleDto article;
final List<String> degradedFields;
}
ArticleDecode decodeArticle(Map<String, dynamic> raw) {
// 复制输入,避免兼容处理反向修改 HTTP 层持有的原始 Map。
final normalized = Map<String, dynamic>.from(raw);
final degradedFields = <String>[];
final publishedAt = normalized['publishedAt'];
// 只有非关键展示字段允许降级,并显式记录发生过兼容处理。
if (publishedAt != null) {
final parsed = publishedAt is String
? DateTime.tryParse(publishedAt)
: null;
if (parsed == null) {
normalized['publishedAt'] = null;
degradedFields.add('publishedAt');
}
}
return ArticleDecode(
article: ArticleDto.fromJson(normalized),
degradedFields: degradedFields,
);
}这个策略的生效行为很明确:publishedAt 为非法日期或错误类型时得到 null,同时 degradedFields 包含 publishedAt;id 或 title 缺失、类型不匹配时仍然让对象解析失败。调用方应把降级字段送入日志或指标系统,而不是只取 article 后丢掉诊断信息。
列表脏一条时隔离单个元素
列表接口还需要决定“一个元素坏掉,是否让整个列表失败”。如果每条元素彼此独立,并且少一条不会改变业务含义,可以逐条解析,只过滤确认属于序列化失败的元素。
下面是片段示例,依赖前面的 ArticleDto 与 decodeArticle,并假设项目已经开启 json_serializable 的 checked 转换:
import 'package:json_annotation/json_annotation.dart';
final class DecodedList<T> {
const DecodedList({
required this.items,
required this.rejectedIndexes,
required this.degradedFieldsByIndex,
});
final List<T> items;
final List<int> rejectedIndexes;
final Map<int, List<String>> degradedFieldsByIndex;
}
DecodedList<ArticleDto> decodeArticles(Object? value) {
if (value is! List) {
throw const FormatException('Expected a JSON array');
}
final items = <ArticleDto>[];
final rejectedIndexes = <int>[];
final degradedFieldsByIndex = <int, List<String>>{};
for (var index = 0; index < value.length; index++) {
final raw = value[index];
// 非对象元素无法建立 ArticleDto,但不影响独立的其他元素。
if (raw is! Map<String, dynamic>) {
rejectedIndexes.add(index);
continue;
}
try {
final decoded = decodeArticle(raw);
items.add(decoded.article);
if (decoded.degradedFields.isNotEmpty) {
degradedFieldsByIndex[index] = decoded.degradedFields;
}
} on Object catch (error, stackTrace) {
// 只过滤明确的数据解析错误;其他异常继续抛出。
final isDataError = error is CheckedFromJsonException ||
error is FormatException ||
error is TypeError;
if (!isDataError) {
Error.throwWithStackTrace(error, stackTrace);
}
rejectedIndexes.add(index);
}
}
return DecodedList(
items: items,
rejectedIndexes: rejectedIndexes,
degradedFieldsByIndex: degradedFieldsByIndex,
);
}返回被拒绝的索引而不是直接丢弃信息,是为了让调用方或监控层知道发生了兼容处理。若接口返回 20 条而过滤了 1 条,可以继续展示 19 条;如果连续出现大量过滤,则应把它视为接口契约回归,而不是“正常容错”。
不适合局部过滤的情况
局部过滤只适合元素彼此独立的集合。购物车金额明细、权限列表、分页游标关联数据等场景中,少一条可能改变业务判断,这时宁愿让整批失败,也不要返回看似成功但语义已经错误的结果。
同样,如果某个子对象虽然标记为可选,但后续逻辑默认它存在,就不能简单返回 null。降级策略必须由业务语义决定,而不是由“能不能避免抛异常”决定。
让兼容处理可观测
每次字段降级或元素过滤至少应留下接口名、模型名、字段或索引、错误类型和计数等信号。可以通过日志、埋点或错误监控聚合这些信息,但不要记录未经脱敏的完整 JSON。
一个健康的数据边界不是“永远不报错”,而是关键契约破坏时明确失败,可恢复的局部异常被限制在最小范围内,并且所有降级都有可追踪的证据。