跨平台开发 / 系统课时
用 FormData 上传单个文件
用 FormData 上传单个文件
这一课完成一个最小可运行的单文件上传:把本地文件包装成 MultipartFile,放入 FormData,再由 Dio 发送 multipart/form-data 请求,并从测试服务的回显中确认文件确实进入了文件字段。
学习目标
- 理解
FormData与MultipartFile在单文件上传中的职责 - 使用 Dio 构造并发送一个完整的 multipart 请求
- 能根据字段名、文件名和响应结果检查上传是否正确
单文件上传的请求结构
普通 JSON 请求会把整个请求体按 JSON 编码,而文件上传通常需要 multipart/form-data。这种请求把一个请求体拆成多个 part,每个 part 都有自己的字段名;文件 part 还会携带文件名等信息。
在 Dio 中,FormData 负责组织这些 part,MultipartFile 负责描述文件内容。后端如果约定文件字段名为 file,客户端就必须使用同样的名字,否则即使 HTTP 请求成功,服务端也可能读不到目标文件。
构造并发送 FormData
以下示例假设项目已经加入 dio 依赖。程序先生成一个临时文本文件,再上传到 httpbin 的 /post 测试接口。该接口会回显接收到的表单和文件内容,适合验证 multipart 请求结构。
import 'dart:io';
import 'package:dio/dio.dart';
Future<void> main() async {
final file = File(
'${Directory.systemTemp.path}/anystack-upload-demo.txt',
);
// 用临时文件保证示例不依赖相册或文件选择器。
await file.writeAsString('hello multipart');
try {
// 字段名 file 必须与服务端接收参数保持一致。
final formData = FormData.fromMap({
'file': await MultipartFile.fromFile(
file.path,
filename: 'upload-demo.txt',
),
});
// 直接把 FormData 交给 Dio,由它生成 multipart 请求体和 boundary。
final response = await Dio().post<Map<String, dynamic>>(
'https://httpbin.org/post',
data: formData,
);
final files = Map<String, dynamic>.from(
response.data!['files'] as Map,
);
print(response.statusCode);
print(files['file']);
} finally {
if (await file.exists()) {
await file.delete();
}
}
}预期输出
200
hello multipartMultipartFile.fromFile 会从文件路径读取内容;filename 是服务端在 multipart 元数据中看到的文件名,不必与本地真实文件名完全相同。FormData 会生成 multipart 所需的边界信息,不需要自己拼接请求体。
上传失败时先检查什么
如果服务端返回“缺少文件”,优先核对接口文档中的字段名。例如后端接收参数叫 avatar,客户端也必须把 file 改成 avatar。字段名不匹配是最常见、也最容易忽略的问题。
如果请求在读取文件前就失败,应先确认路径存在且应用有权读取;如果服务器返回 4xx 或 5xx,则查看 DioException.response 中的状态码和响应体,不要把所有失败都归因于文件本身。
在真实业务中,只需要把示例中的临时文件路径替换为文件选择器、相机或图片选择器得到的实际路径,并把请求地址与字段名替换成后端接口约定即可。