跨平台开发 / 系统课时
同时上传文件和普通字段
同时上传文件和普通字段
很多上传接口除了附件,还要求标题、业务类型或描述等普通参数。本课把这些值和文件放进同一个 FormData,一次请求完成提交,并验证服务端能分别收到普通字段与文件字段。
学习目标
- 在一个
FormData中组合普通字段和文件字段 - 理解字段名如何与后端 multipart 参数一一对应
- 通过回显结果验证文本参数和文件都被正确提交
FormData 如何区分字段类型
FormData.fromMap 可以同时接收字符串等普通值和 MultipartFile。普通值会成为表单字段,MultipartFile 会成为文件 part,因此客户端不需要发送两次请求。
例如接口约定 title、type 和 attachment 三个参数,其中前两个是文本,最后一个是文件,那么客户端应直接使用这三个名字构造表单。是否叫 file、image 还是 attachment 并没有统一规定,必须以服务端契约为准。
一次提交文本和附件
下面的完整示例创建一个临时文件,同时提交标题、类型和附件。为了便于验证,请求仍发送到 httpbin 的 /post 接口,并只打印需要检查的字段。
import 'dart:io';
import 'package:dio/dio.dart';
Future<void> main() async {
final file = File(
'${Directory.systemTemp.path}/anystack-report.txt',
);
// 用临时文件让示例可以独立运行,不依赖选择文件界面。
await file.writeAsString('report body');
try {
// 普通值和 MultipartFile 可以放在同一个 FormData 中。
final formData = FormData.fromMap({
'title': 'September report',
'type': 'document',
'attachment': await MultipartFile.fromFile(
file.path,
filename: 'report.txt',
),
});
// 服务器会按字段名分别读取文本 part 与文件 part。
final response = await Dio().post<Map<String, dynamic>>(
'https://httpbin.org/post',
data: formData,
);
final data = response.data!;
final form = Map<String, dynamic>.from(data['form'] as Map);
final files = Map<String, dynamic>.from(data['files'] as Map);
print(response.statusCode);
print(form['title']);
print(form['type']);
print(files['attachment']);
} finally {
if (await file.exists()) {
await file.delete();
}
}
}预期输出
200
September report
document
report body从结果可以看出,title 和 type 出现在普通表单字段中,而 attachment 出现在文件字段中。三者虽然共用一个 HTTP 请求,但服务端仍能按各自的字段名分别读取。
业务字段要按接口契约编码
所有 multipart 参数都应使用后端定义的键名。若后端要求 asset_type,客户端却发送 type,HTTP 层可能仍返回成功,但业务层会因为缺少参数而拒绝请求。
需要上传数字、布尔值或枚举时,也应先确认服务端如何解析 multipart 文本字段。最稳妥的做法是按接口文档发送明确的字符串形式,而不是假设服务端会自动完成任意类型转换。
什么时候拆成两个请求
文件与元数据属于同一次业务提交时,单个 FormData 最简单,例如创建资料时同时上传封面和标题。若文件需要先上传对象存储、再把返回的文件 ID 写入业务接口,则应遵循后端设计拆成两个步骤,而不是强行把所有数据塞进一个 multipart 请求。
只要服务端接口定义为一次 multipart 提交,就让普通字段与文件共同进入同一个 FormData;字段名、文件名和业务值都以接口契约为准。