Flutter图片文件上传最佳实践咨询：错误处理与重传等场景

一、基础上传规范 #

• 本地前置校验：上传前先在客户端做校验，避免无效请求：
  • 文件类型：同时检查后缀名和MIME类型（比如用Dio的MultipartFile.fromFile时指定contentType），拒绝非允许格式的文件；
  • 文件大小：提前判断是否超出后端限制，比如提示“文件大小不能超过10MB”；
  • 文件存在性：确认本地文件未被删除或损坏。
• 正确使用Multipart格式：Retrofit中用@Multipart注解标记接口，配合@Part("file") MultipartFile file定义参数；Dio层面确保自动生成Content-Type: multipart/form-data请求头。
• 大文件分块上传：对超过10MB的文件，按固定大小（比如1MB）切割成多个块，分批次上传，最后通知后端合并。Dio可开启chunkedMode，或自行实现分块逻辑（每个请求携带块序号、总块数、文件唯一标识）。
• 进度监听：利用Dio的onSendProgress回调实时获取上传进度，同步到UI层提升用户体验：

  dio.post(
    "/upload",
    data: formData,
    onSendProgress: (sent, total) {
      double progress = sent / total;
      // 更新进度条或百分比显示
    },
  );
  

二、错误处理策略 #

• 分类捕获错误：针对不同错误类型给出对应处理：
  • 客户端错误（4xx状态码）：比如参数错误、文件格式不合法，直接提示用户修正操作（如“请选择JPG/PNG格式的图片”）；
  • 服务端错误（5xx状态码）：提示用户“服务器繁忙，请稍后重试”，不要暴露技术细节；
  • 网络错误：捕获Dio的DioErrorType.connectTimeout/receiveTimeout等类型，提示用户检查网络连接。
• 代码层面捕获异常：用try-catch包裹Retrofit请求，精准处理DioError：

  try {
    await apiService.uploadImage(multipartFile);
  } on DioError catch (e) {
    if (e.type == DioErrorType.connectionTimeout) {
      // 处理超时
    } else if (e.response?.statusCode == 400) {
      // 处理参数或格式错误
    }
  }
  

三、重传机制实现 #

• 限定重传范围：仅对可恢复错误重试，比如网络中断、服务端5xx错误；客户端4xx错误（如文件格式错）无需重试，避免无效请求。
• 限制重传次数：设置最大重试次数（比如3次），防止无限重试浪费资源。
• 指数退避策略：每次重试间隔时间递增（如1s→2s→4s），避免短时间内频繁请求压垮服务器。可通过Dio拦截器实现：

  class RetryInterceptor extends Interceptor {
    final int maxRetryTimes;
  
    RetryInterceptor(this.maxRetryTimes);
  
    @override
    Future<void> onError(DioError err, ErrorInterceptorHandler handler) async {
      if (_shouldRetry(err)) {
        int retryCount = 0;
        while (retryCount < maxRetryTimes) {
          try {
            await Future.delayed(Duration(seconds: 1 << retryCount));
            final response = await dio.request(
              err.requestOptions.path,
              options: Options(
                method: err.requestOptions.method,
                headers: err.requestOptions.headers,
              ),
              data: err.requestOptions.data,
            );
            return handler.resolve(response);
          } catch (_) {
            retryCount++;
          }
        }
      }
      handler.next(err);
    }
  
    bool _shouldRetry(DioError err) {
      return err.type == DioErrorType.connectionTimeout ||
          err.type == DioErrorType.receiveTimeout ||
          err.type == DioErrorType.sendTimeout ||
          (err.response?.statusCode != null && err.response!.statusCode! >= 500);
    }
  }
  

  然后将拦截器添加到Dio实例：dio.interceptors.add(RetryInterceptor(3));

四、额外优化建议 #

• 图片压缩：上传前用image库压缩图片，降低文件大小（比如压缩到1080px宽、80%质量），减少上传时间和流量消耗：

  import 'package:image/image.dart' as img;
  
  Future<File> compressImage(File file) async {
    final image = img.decodeImage(await file.readAsBytes())!;
    final compressedImage = img.copyResize(image, width: 1080);
    final compressedFile = File('${file.path}_compressed.jpg');
    await compressedFile.writeAsBytes(img.encodeJpg(compressedImage, quality: 80));
    return compressedFile;
  }
  

• 断点续传：大文件上传时，记录已上传的块序号，下次上传时仅传输未完成的块（需后端支持断点续传接口，通过文件唯一标识校验已上传块）。
• 上传取消：给Dio请求绑定CancelToken，支持用户主动取消上传：

  CancelToken cancelToken = CancelToken();
  // 发起上传
  dio.post("/upload", data: formData, cancelToken: cancelToken);
  // 用户取消时调用
  cancelToken.cancel("上传已取消");
  

• 避免重复上传：给每个文件生成唯一MD5标识，上传前先调用后端接口校验文件是否已存在，若存在直接返回结果，无需重复上传。

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