跨平台开发 / 系统课时

排查字段类型与空值异常

排查字段类型与空值异常

接口一旦出现 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 可以缺失,所以声明为可空。

dart
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 片段通常会呈现类似下面的转换链;具体格式可能随生成器版本变化,但检查思路一致。

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,比直接连接真实接口更容易确认边界。下面的测试分别覆盖旧版字符串价格、缺失必填键和转换器拒绝非法类型三种情况。

dart
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>()),
    );
  });
}

运行测试:

bash
flutter test test/product_dto_test.dart -r expanded

预期输出中时间值会因机器而异:

text
<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 重新执行生成和测试,并再对一次真实响应。修复后的目标不是“这次不崩”,而是异常能准确暴露真正违约的数据,同时合法的兼容输入仍然稳定通过。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查字段类型与空值异常

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

登录哪都通