基于Swagger API上传图片至服务器：Flutter中fileToken用法咨询

一、fileToken 参数解释 #

从你提供的Swagger API截图来看，fileToken是服务端预生成的文件唯一标识，核心作用：

• 提前告知服务端即将接收的文件信息，拦截非法上传请求；
• 关联服务端内部的文件存储路径、元数据，确保上传后能正确识别和归档文件；
• 必须先调用服务端的「获取上传凭证」前置接口（比如/api/file/get-upload-token这类接口，具体看你们的业务文档），才能拿到有效的fileToken。

二、Flutter 上传具体实现步骤 #

1. 先获取有效的 fileToken #

调用服务端提供的前置接口，传入文件类型、业务标识等必要参数（具体看接口要求），拿到返回的fileToken值，这是上传的前置条件。

2. 选择上传库实现（推荐用 dio，处理文件更便捷） #

下面分别给出两种常用库的实现代码：

方式一：使用 dio 库上传

先在pubspec.yaml中添加依赖：

dependencies:
  dio: ^5.0.0 # 选用最新稳定版本即可

上传代码示例：

import 'package:dio/dio.dart';
import 'package:path/path.dart';

Future<void> uploadImage(String imagePath, String fileToken) async {
  try {
    final dio = Dio();
    // 构造FormData，参数名必须和Swagger定义的完全一致：`file`、`fileToken`
    final formData = FormData.fromMap({
      'file': await MultipartFile.fromFile(
        imagePath,
        filename: basename(imagePath), // 保留原文件名，也可自定义
      ),
      'fileToken': fileToken,
    });

    final response = await dio.post(
      'https://your-server-domain.com/upload', // 替换成Swagger里的实际接口地址
      data: formData,
      options: Options(
        // 接口需要身份验证时，添加请求头
        headers: {'Authorization': 'Bearer ${yourAuthToken}'},
      ),
    );

    if (response.statusCode == 200) {
      print('上传成功：${response.data}');
      // 这里处理上传成功后的业务逻辑，比如保存返回的文件URL
    } else {
      print('上传失败，状态码：${response.statusCode}');
    }
  } catch (e) {
    print('上传出错：$e');
  }
}

方式二：使用原生 http 库上传

添加依赖（mime用来识别文件类型）：

dependencies:
  http: ^1.0.0
  mime: ^1.0.0

上传代码示例：

import 'package:http/http.dart' as http;
import 'package:path/path.dart';
import 'package:mime/mime.dart';

Future<void> uploadImageWithHttp(String imagePath, String fileToken) async {
  try {
    final mimeType = lookupMimeType(imagePath) ?? 'image/jpeg';
    final request = http.MultipartRequest(
      'POST',
      Uri.parse('https://your-server-domain.com/upload'), // 替换成实际接口地址
    );

    // 添加文件参数
    request.files.add(
      await http.MultipartFile.fromPath(
        'file',
        imagePath,
        filename: basename(imagePath),
        contentType: MediaType.parse(mimeType),
      ),
    );

    // 添加fileToken参数
    request.fields['fileToken'] = fileToken;

    // 身份验证头（如果接口需要）
    // request.headers['Authorization'] = 'Bearer ${yourAuthToken}';

    final response = await request.send();
    final responseBody = await http.Response.fromStream(response);

    if (response.statusCode == 200) {
      print('上传成功：${responseBody.body}');
    } else {
      print('上传失败：状态码${response.statusCode}，响应内容：${responseBody.body}');
    }
  } catch (e) {
    print('上传出错：$e');
  }
}

3. 关键注意事项 #

• 确保file和fileToken的参数名、大小写和Swagger文档完全匹配；
• 图片路径必须有效，比如从相册选择的文件路径、相机拍摄后保存的本地路径；
• 接口有权限校验时，必须在请求头中携带有效的身份凭证（比如JWT Token）；
• 测试阶段可以打印请求详情，排查参数传递、请求头配置是否正确。

内容的提问来源于stack exchange，提问作者user14774662