跨平台开发 / 系统课时

同时上传文件和普通字段

同时上传文件和普通字段

很多上传接口除了附件,还要求标题、业务类型或描述等普通参数。本课把这些值和文件放进同一个 FormData,一次请求完成提交,并验证服务端能分别收到普通字段与文件字段。

学习目标

  • 在一个 FormData 中组合普通字段和文件字段
  • 理解字段名如何与后端 multipart 参数一一对应
  • 通过回显结果验证文本参数和文件都被正确提交

FormData 如何区分字段类型

FormData.fromMap 可以同时接收字符串等普通值和 MultipartFile。普通值会成为表单字段,MultipartFile 会成为文件 part,因此客户端不需要发送两次请求。

例如接口约定 title、type 和 attachment 三个参数,其中前两个是文本,最后一个是文件,那么客户端应直接使用这三个名字构造表单。是否叫 file、image 还是 attachment 并没有统一规定,必须以服务端契约为准。

一次提交文本和附件

下面的完整示例创建一个临时文件,同时提交标题、类型和附件。为了便于验证,请求仍发送到 httpbin 的 /post 接口,并只打印需要检查的字段。

dart
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();
    }
  }
}

预期输出

text
200
September report
document
report body

从结果可以看出,title 和 type 出现在普通表单字段中,而 attachment 出现在文件字段中。三者虽然共用一个 HTTP 请求,但服务端仍能按各自的字段名分别读取。

业务字段要按接口契约编码

所有 multipart 参数都应使用后端定义的键名。若后端要求 asset_type,客户端却发送 type,HTTP 层可能仍返回成功,但业务层会因为缺少参数而拒绝请求。

需要上传数字、布尔值或枚举时,也应先确认服务端如何解析 multipart 文本字段。最稳妥的做法是按接口文档发送明确的字符串形式,而不是假设服务端会自动完成任意类型转换。

什么时候拆成两个请求

文件与元数据属于同一次业务提交时,单个 FormData 最简单,例如创建资料时同时上传封面和标题。若文件需要先上传对象存储、再把返回的文件 ID 写入业务接口,则应遵循后端设计拆成两个步骤,而不是强行把所有数据塞进一个 multipart 请求。

只要服务端接口定义为一次 multipart 提交,就让普通字段与文件共同进入同一个 FormData;字段名、文件名和业务值都以接口契约为准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

同时上传文件和普通字段

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通