在Dio中处理Multipart请求时发送JSON内嵌文件的最佳实践

问题背景

在使用Dio进行网络请求时，开发者经常会遇到需要发送复杂数据结构的情况，特别是当请求中既包含普通字段又包含文件上传时。本文讨论的场景是：如何在Dio中构建一个Multipart请求，其中包含JSON格式的数据，而JSON数据中又嵌套了文件对象。

核心挑战

开发者在尝试构建这样的请求时遇到了一个常见错误："Converting object to an encodable object failed: Instance of 'MapEntry<String, MultipartFile>'"。这个错误的本质在于尝试直接将MultipartFile对象放入JSON结构中，而JSON序列化无法处理这种特殊类型。

解决方案详解

1. 理解FormData的结构

Dio中的FormData可以同时处理普通字段和文件字段。关键是要理解：

• 普通字段使用fields属性添加
• 文件字段使用files属性添加
• 复杂JSON结构需要适当拆分

2. 正确的实现方式

对于原始问题中的数据结构，应该这样处理：

FormData data = FormData();
// 添加普通字段
data.fields.add(MapEntry('VisaAppointmentId', visaAppointmentId.toString()));

// 处理删除的文档列表
for (var element in deletedDocuments) {
  data.fields.add(MapEntry('DeletedDocuments', element.toString()));
}

// 处理新文档列表
for (var documentRequest in newDocuments) {
  String fileName = documentRequest.document!.path.split('/').last;
  List<int> bytes = await documentRequest.document!.readAsBytes();
  
  var contentType = lookupMimeType(documentRequest.document!.path);
  var parts = contentType!.split('/');
  var mediaType = MediaType(parts[0], parts[1]);

  // 为每个文件创建唯一标识
  String fileKey = 'document_${DateTime.now().millisecondsSinceEpoch}';
  
  // 添加文件到FormData
  data.files.add(MapEntry(
    fileKey,
    MultipartFile.fromBytes(
      bytes,
      filename: fileName,
      contentType: mediaType,
    ),
  ));

  // 在JSON中引用这个文件
  Map<String, dynamic> documentMap = {
    'documentType': documentRequest.documentType,
    'document': fileKey, // 使用文件引用而不是直接放入文件
    'visaApplicantId': documentRequest.visaApplicantId,
  };

  // 将文档信息添加到列表中
  newDocumentsList.add(documentMap);
}

// 将文档列表转为JSON字符串
String newDocumentsJson = jsonEncode(newDocumentsList);
data.fields.add(MapEntry('NewDocuments', newDocumentsJson));

3. 服务器端处理

服务器端需要能够理解这种结构：

1. 解析VisaAppointmentId和DeletedDocuments字段
2. 解析NewDocumentsJSON字符串
3. 根据JSON中的文件引用找到对应的文件内容

进阶技巧

处理多个文件

当需要上传多个文件时，可以为每个文件生成唯一的key，并在JSON中使用这些key引用文件。

性能优化

对于大文件，考虑使用流式上传而不是一次性读取所有字节，可以减少内存使用。

错误处理

添加适当的错误处理逻辑，包括：

• 文件读取失败
• JSON序列化失败
• 网络请求失败

总结

在Dio中处理包含嵌套文件的JSON结构时，关键在于将文件与JSON引用分离。通过为每个文件创建唯一标识并在JSON中引用这些标识，可以避免直接序列化MultipartFile对象的问题。这种方法既保持了数据结构的清晰性，又符合HTTP multipart/form-data的规范。