跨平台开发 / 系统课时

用 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 请求结构。

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

预期输出

text
200
hello multipart

MultipartFile.fromFile 会从文件路径读取内容;filename 是服务端在 multipart 元数据中看到的文件名,不必与本地真实文件名完全相同。FormData 会生成 multipart 所需的边界信息,不需要自己拼接请求体。

上传失败时先检查什么

如果服务端返回“缺少文件”,优先核对接口文档中的字段名。例如后端接收参数叫 avatar,客户端也必须把 file 改成 avatar。字段名不匹配是最常见、也最容易忽略的问题。

如果请求在读取文件前就失败,应先确认路径存在且应用有权读取;如果服务器返回 4xx 或 5xx,则查看 DioException.response 中的状态码和响应体,不要把所有失败都归因于文件本身。

在真实业务中,只需要把示例中的临时文件路径替换为文件选择器、相机或图片选择器得到的实际路径,并把请求地址与字段名替换成后端接口约定即可。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 FormData 上传单个文件

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

登录哪都通