Flutter中API空响应引发List与Map类型不匹配异常的处理方法

异常「type List is not a subtype of type Map<String, dynamic>」的核心原因是：空数据时API返回的是List类型，但你的TransactionsList.fromJson方法只接受Map<String, dynamic>类型参数，类型不匹配导致解析失败。

需要在解析JSON前先判断响应类型，同时在模型类中增加空值安全处理，避免空指针异常。

1. 修改JSON解析入口函数 #

在transactionsListFromJson中先判断解析后的JSON数据类型，区分正常Map响应和空List响应：

import 'dart:convert';

TransactionsList transactionsListFromJson(String str) {
  final jsonData = json.decode(str);
  // 空数据时API返回List，返回预设空值的TransactionsList实例
  if (jsonData is List) {
    return TransactionsList(
      type: "success",
      message: "No data",
      paidTotalRecords: 0,
      paidTotalAmount: PaidTotalAmount(lkr: "0"),
      paidRecordData: [],
    );
  }
  // 正常Map类型响应，按原有逻辑解析
  return TransactionsList.fromJson(jsonData);
}

// 其他代码保持不变...

2. 增强模型类的空值安全处理 #

原模型类存在强制解包（!）的崩溃风险，同时需要处理字段为空的情况：

class TransactionsList {
  String? type;
  String? message;
  int? paidTotalRecords;
  PaidTotalAmount? paidTotalAmount;
  List<PaidRecordDatum>? paidRecordData;

  TransactionsList({
    this.type,
    this.message,
    this.paidTotalRecords,
    this.paidTotalAmount,
    this.paidRecordData,
  });

  factory TransactionsList.fromJson(Map<String, dynamic> json) => TransactionsList(
        type: json["type"],
        message: json["message"],
        paidTotalRecords: json["paid_TotalRecords"],
        // 处理paid_TotalAmount为空的情况
        paidTotalAmount: json["paid_TotalAmount"] != null 
            ? PaidTotalAmount.fromJson(json["paid_TotalAmount"]) 
            : PaidTotalAmount(lkr: "0"),
        // 处理paid_recordData为空的情况
        paidRecordData: json["paid_recordData"] != null
            ? List<PaidRecordDatum>.from(
                json["paid_recordData"].map((x) => PaidRecordDatum.fromJson(x)))
            : [],
      );

  Map<String, dynamic> toJson() => {
        "type": type,
        "message": message,
        "paid_TotalRecords": paidTotalRecords,
        // 避免强制解包，用空值合并运算符处理
        "paid_TotalAmount": paidTotalAmount?.toJson() ?? PaidTotalAmount(lkr: "0").toJson(),
        "paid_recordData": paidRecordData?.map((x) => x.toJson()).toList() ?? [],
      };
}

3. 额外建议 #

如果有条件，建议和后端确认是否可以统一返回Map类型的响应（比如空数据时返回{"type":"success", "message":"No data", "paid_TotalRecords":0, ...}），这样前端解析逻辑可以更简洁，无需额外的类型判断。

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