Flutter中解析包含Map列表的JSON文件为Dart文件及Dio类型转换报错排查

你遇到的这个错误核心原因很明确：后端返回的JSON结构和你的Dart模型不匹配。错误提示type 'List' is not a subtype of type 'Map<String, dynamic>?'说明，你的代码期望解析一个包含列表的对象（Map），但实际后端返回的是一个直接的数组（List）。

先理清结构差异 #

看你定义的NoteResponse类，它默认期望的JSON结构是这样的（包含noteDataResponse字段的对象）：

{
  "noteDataResponse": [
    {"text": "xxx", "placeDateTime": "xxx", "userId": "xxx", "id": "xxx"},
    // 更多笔记对象
  ],
  // BaseResponse的其他字段，比如code、message等
}

但实际你的接口返回的是直接的笔记数组：

[
  {"text": "xxx", "placeDateTime": "xxx", "userId": "xxx", "id": "xxx"},
  // 更多笔记对象
]

这种结构不匹配直接导致了类型转换失败。

分场景给出解决方案 #

场景1：后端确实返回直接的List数组（多数业务场景是这样） #

直接抛弃NoteResponse类，把返回的List直接解析成List<NoteDataResponse>即可，修改你的Dio请求代码：

// 假设你之前的请求代码是这样
Response response = await dio.get('/your-notes-api');

// 替换原来的NoteResponse.fromJson解析逻辑
List<NoteDataResponse> noteList = (response.data as List)
    .map((item) => NoteDataResponse.fromJson(item as Map<String, dynamic>))
    .toList();

场景2：你需要后端返回包含列表的对象（和NoteResponse模型匹配） #

这时候需要先确认后端接口的返回结构：

• 优先要求后端调整返回格式，返回包含noteDataResponse字段的JSON对象，同时带上BaseResponse的其他字段（比如状态码、提示信息）
• 如果后端无法修改，也可以临时调整NoteResponse的解析逻辑来适配List输入：

// 修改NoteResponse的fromJson方法
factory NoteResponse.fromJson(dynamic json) {
  if (json is List) {
    return NoteResponse(
      json.map((item) => NoteDataResponse.fromJson(item)).toList()
    );
  } else if (json is Map<String, dynamic>) {
    return _$NoteResponseFromJson(json);
  }
  throw ArgumentError('Invalid JSON type');
}

不过这种写法不够规范，更推荐按实际返回结构调整模型。

实用调试小技巧 #

建议先打印返回数据的类型和内容，明确后端到底返回了什么：

Response response = await dio.get('/your-notes-api');
print('返回数据类型：${response.data.runtimeType}');
print('返回数据内容：$response.data');

这样能快速定位结构不匹配的问题，避免盲目猜谜。

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