跨平台开发 / 系统课时

隔离部分失真的接口数据

隔离部分失真的接口数据

真实接口常出现“主体可用、局部字段脏掉”的情况,例如可选日期格式异常、某个子对象结构改变,或列表里只有一条记录损坏。本节建立分级处理策略,在保证关键契约不被掩盖的前提下,让可恢复的数据继续进入应用。

学习目标

  • 判断何时应该整条响应失败,何时可以字段降级或过滤局部记录
  • 为可选脏字段编写边界明确的兼容转换
  • 在降级后保留监控信号,避免兼容逻辑长期掩盖接口回归

先按契约重要性决定策略

处理脏数据前先问两个问题:这个字段是否决定对象身份或业务正确性;丢失它之后,应用是否还能明确地解释这条数据。id、金额、权限状态等关键字段通常不适合静默降级,而头像地址、可选备注、非关键展示时间则可能允许回退为 null。

常见策略可以分成三类:关键字段异常时让整条对象失败;可选字段异常时回退到安全值;列表中的独立元素异常时过滤该元素,但必须记录被过滤的位置和数量。

部分失真数据的降级决策流程

可选字段只在边界内降级

下面的 Freezed 模型把 publishedAt 定义为可选展示字段。与其在转换器里悄悄吞掉错误,这里先规范化原始 JSON:只有该字段异常时才回退为 null,同时把降级字段返回给调用方;id 与 title 仍保持严格非空类型。

这是片段示例,依赖 Freezed/json_serializable 的生成文件:

dart
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 转换:

dart
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。

一个健康的数据边界不是“永远不报错”,而是关键契约破坏时明确失败,可恢复的局部异常被限制在最小范围内,并且所有降级都有可追踪的证据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

隔离部分失真的接口数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通