Flutter中如何使用Dio将嵌套Map转换为服务器可正确解析的FormData格式

我之前也踩过一模一样的坑！直接把嵌套Map塞进FormData里，后端要么收到的是Instance of Map<String, dynamic>字符串，要么布尔值、数字被转成字符串导致解析失败。后来查了multipart/form-data的规范才明白：要把嵌套结构展开成父键[子键][孙键]: 值的格式，后端（不管是Laravel还是Express）才能正确识别为嵌套对象。

核心思路 #

写一个递归工具函数，把嵌套的Map逐层展开，生成符合multipart规范的键值对结构，这样后端框架会自动把这些键解析成嵌套的对象/数组，同时保留布尔值、数字的原始类型。

实现步骤 #

1. 编写扁平化嵌套Map的工具函数

这个函数会递归遍历嵌套Map，把所有层级的键拼接成parent[child][grandchild]的格式：

Map<String, dynamic> flattenNestedMap(Map<String, dynamic> map, [String? parentKey]) {
  final result = <String, dynamic>{};

  map.forEach((key, value) {
    // 拼接当前层级的键名
    final currentKey = parentKey != null ? '$parentKey[$key]' : key;

    if (value is Map<String, dynamic>) {
      // 如果值还是嵌套Map，递归处理
      result.addAll(flattenNestedMap(value, currentKey));
    } else {
      // 基础类型直接存入，保持原始类型（布尔值、数字不会被转成字符串）
      result[currentKey] = value;
    }
  });

  return result;
}

2. 用工具函数处理嵌套结构并构建FormData

先把你的deviceSettings扁平化，再和其他字段、文件一起组装成FormData：

// 定义你的嵌套设备设置
final deviceSettings = {
  "sound_settings": {
    "enabled": true,
    "volume": 80,
    "default_sounds": {
      "success": "success.mp3",
      "failure": "fail.mp3",
      "unlock": "unlock.mp3",
    }
  },
  "brightness_settings": {
    "enabled": false,
    "intensity": 60
  }
};

// 1. 扁平化嵌套的设备设置，指定根键为device_settings
final flattenedSettings = flattenNestedMap(deviceSettings, 'device_settings');

// 2. 组装基础FormData字段（包含扁平化后的设置）
final baseFields = {
  "name": "Device Name",
  "serial_number": "XYZ123",
  ...flattenedSettings, // 展开扁平化后的所有键值对
};

// 3. 添加文件并创建最终的FormData
final formData = FormData.fromMap({
  ...baseFields,
  "background": await MultipartFile.fromFile("path/to/image.jpg"),
});

效果验证 #

扁平化后，你的FormData会包含这些键值对：

device_settings[sound_settings][enabled]: true
device_settings[sound_settings][volume]: 80
device_settings[sound_settings][default_sounds][success]: success.mp3
device_settings[brightness_settings][enabled]: false
...

后端框架会自动把这些键解析成嵌套的对象，布尔值、数字都保持原始类型，不会出现字符串化的问题。

扩展注意点 #

• 如果你的嵌套结构里有List（数组），可以扩展工具函数，把数组元素转成parentKey[0]、parentKey[1]的格式，后端会识别为数组。
• 如果值为null，可根据后端需求决定是否保留该键，比如在函数里加判断if (value != null) result[currentKey] = value;。
• MultipartFile类型的字段要单独处理，不要放进扁平化函数里，避免被错误解析。

内容来源于stack exchange