Dart JSON反序列化报错type '_InternalLinkedHashMap<String, dynamic>' is not a subtype of type 'List'排查

错误产生原因 #

该错误是Dart类型系统在运行时检测到类型不匹配：你代码中某字段声明为List类型，但JSON解析后得到的实际值是Map<String, dynamic>类型，强制类型转换失败抛出异常。结合你提供的代码，具体触发原因有3个：

1. JSON结构语法错误，和实体类定义不匹配
   你给出的JSON中Instytucja字段使用数组[]直接包裹键值对，不符合JSON语法规范（JSON数组只能存放值，键值对必须放在对象{}中）。如果Instytucja对应单个机构对象，你却在实体类中把institutions定义为List<InstitutionModel>，就会直接触发该类型转换错误。
2. 字段名拼写不匹配
   JSON中单位列表的键名为Jendostka，但InstitutionModel中units字段的@JsonKey注解配置的name为Jednostka，拼写不一致会导致字段解析失败，也可能间接触发类型异常。
3. json_serializable未配置嵌套泛型支持
   你使用了多层嵌套的泛型模型（如List<InstitutionModel>），但没有开启genericArgumentFactories配置，生成的反序列化代码不会自动调用内部模型的fromJson方法，直接把Map值赋值给List类型字段就会抛出异常。

解决步骤 #

1. 修正JSON结构，和实体类对齐
   如果Instytucja是单个机构对象，修改JSON结构为：

{
  "Instytucja": {
    "TypInstytucji": "bank krajowy",
    "PodtypInstytucji": "bank centralny",
    "NrInstytucji": 101,
    "NazwaInstytucji": "Narodowy Bank Polski",
    "SymbolLiterowy": "NBP",
    "DataRozpDzial": "1945-01-15",
    "NIP": 5250008198,
    "IdentyfikatorLEI": "549300K7Z2KT76WQJD18",
    "WWW": "www.nbp.pl",
    "Jednostka": [
      {
        "NrEwidencyjny": "A000001",
        // 剩余单位字段
      }
    ]
  }
}

同时修改Bank抽象类和BankModel的字段定义，把List<Institution>改为单个Institution类型：

// 抽象类修改
abstract class Bank extends Equatable {
  Institution get institution;
}

// BankModel修改
@JsonSerializable()
class BankModel extends Bank {
  BankModel({required this.institution});

  factory BankModel.fromJson(Map<String, dynamic> json) => _$BankModelFromJson(json);

  @override
  @JsonKey(name: 'Instytucja')
  final InstitutionModel institution;

  @override
  List<Object?> get props => [institution];
}

如果Instytucja确实是机构数组，就把JSON中Instytucja下的键值对用{}包裹成对象放在数组中即可。

2. 修正字段名拼写
   把InstitutionModel中units字段的@JsonKey配置改为和JSON一致：

@override
@JsonKey(name: 'Jendostka')
final List<UnitModel> units;

3. 添加json_serializable配置
   给所有4个模型类的@JsonSerializable注解添加嵌套泛型支持和忽略未声明字段的配置：

@JsonSerializable(
  genericArgumentFactories: true,
  ignoreUnannotated: true,
)
class BankModel extends Bank {
  // 原有代码不变
}
// InstitutionModel、UnitModel、SortNumberModel都添加相同配置

4. 重新生成序列化代码
   在项目根目录运行以下命令重新生成*.g.dart文件：

flutter pub run build_runner build --delete-conflicting-outputs

内容的提问来源于stack exchange，提问作者szakes1