Flutter应用开发：对象存储管理图片

概述

使用七牛云Flutter的SDK qiniu_flutter_sdk 在Flutter物流项目中主要用于车辆相关页面的图片上传功能，包括车辆照片、行驶证照片、商业险照片和道路运输证照片的上传。通过该SDK，实现了图片的快速上传和管理。

SDK初始化配置

在使用SDK之前，需要进行必要的初始化配置：

dart 复制代码

import 'package:qiniu_flutter_sdk/qiniu_flutter_sdk.dart';

void initQiniuSDK() {
  // 配置SDK
  Config config = Config()
    ..connectTimeout = 30000
    ..responseTimeout = 30000
    ..retryMax = 3
    ..retryInterval = 1000;
    
  // 初始化SDK
  Qiniu.init(config);
}

主要应用场景

车辆添加页面 (vehicle_add_form_page.dart)
车辆认证页面 (vehicle_auth_form_page.dart)
车辆编辑页面 (vehicle_update_form_page.dart)

核心功能实现

1. 图片上传

使用 Storage 类进行文件上传，通过 PutController 控制上传过程，并配置 PutOptions 参数。

dart 复制代码

Storage storage = Storage();
PutController putController = PutController();
// qiniuPath生成规则说明：
// 1. uploadPolicy?.filePath：获取上传策略中的基础路径
// 2. imageUseType：图片用途类型（如vehicle_photo, license_photo等）
// 3. DateTime.now().millisecondsSinceEpoch：当前时间戳，确保唯一性
// 4. p.extension(path)：获取文件扩展名
// 5. 增加用户ID和设备ID，进一步确保路径唯一性
String qiniuPath = "${uploadPolicy?.filePath}${imageUseType}_${userId}_${deviceId}_${DateTime.now().millisecondsSinceEpoch}${p.extension(path)}";
putController.addProgressListener((percent) {});
putController.addStatusListener((status) {
  if (status == StorageStatus.Success) {
    // 处理上传成功后的逻辑
  } else if (status == StorageStatus.Error) {
    // 处理上传失败的情况
  }
});
storage.putFile(File(path), uploadPolicy!.uploadToken!, options: PutOptions(controller: putController, key: qiniuPath));

2. 图片删除

通过调用OSS接口删除已上传的图片。

dart 复制代码

await G.req.oss.delFile(_path, "vehicle").then((value) {
  G.loading.hide(context);
  G.toast('移除图片成功');
}).catchError((err) {
  G.loading.hide(context);
});

3. 图片更新逻辑

当需要更新已上传的图片时，按照以下步骤进行：

删除旧图片：先删除服务器上的旧图片
上传新图片：使用新的路径上传新图片
更新数据库：更新本地和服务器端的图片路径记录

dart 复制代码

// 更新图片示例
Future<void> updateImage(String oldPath, String newPath) async {
  try {
    // 1. 删除旧图片
    await G.req.oss.delFile(oldPath, "vehicle");
    
    // 2. 上传新图片
    String newQiniuPath = generateQiniuPath(newPath);
    await storage.putFile(File(newPath), uploadPolicy!.uploadToken!,
        options: PutOptions(key: newQiniuPath));
        
    // 3. 更新数据库
    await updateImagePathInDatabase(oldPath, newQiniuPath);
    
    G.toast('图片更新成功');
  } catch (e) {
    G.toast('图片更新失败: $e');
  }
}

// 生成新的qiniu路径
String generateQiniuPath(String path) {
  return "${uploadPolicy?.filePath}${imageUseType}_${userId}_${deviceId}_${DateTime.now().millisecondsSinceEpoch}${p.extension(path)}";
}

获取上传策略

在文件上传之前，需要先通过认证获取上传策略。使用 G.req.oss.getUploadPolicy 接口获取上传策略对象 OssUploadPolicy。

dart 复制代码

// 获取上传策略示例
OssUploadPolicy? uploadPolicy;
try {
  uploadPolicy = await G.req.oss.getUploadPolicy(
    bucket: "vehicle-images",  // 存储空间名称
    fileType: "image",         // 文件类型
    userId: userId,            // 用户ID
    deviceId: deviceId         // 设备ID
  );
} catch (e) {
  // 处理获取上传策略失败的情况
  print("获取上传策略失败: $e");
}

if (uploadPolicy == null) {
  // 处理上传策略为空的情况
  return;
}

错误处理机制

网络错误处理：捕获网络异常，提供友好的错误提示
上传失败重试：配置重试机制，提高上传成功率
文件校验：上传前进行文件大小和类型校验

dart 复制代码

try {
  // 上传操作
} on NetworkException catch (e) {
  // 处理网络异常
  print('网络异常: ${e.message}');
} on StorageException catch (e) {
  // 处理存储异常
  print('存储异常: ${e.message}');
} catch (e) {
  // 处理其他异常
  print('未知异常: $e');
}

性能优化建议

分片上传：对于大文件，使用分片上传提高成功率
并发控制：合理控制并发上传数量
缓存策略：对上传策略进行缓存，减少重复请求
图片压缩：上传前对图片进行适当压缩

最佳实践

路径规划：合理规划文件存储路径，便于管理
权限控制：根据业务需求设置合适的访问权限
日志记录：记录上传过程中的关键信息
用户反馈：提供实时的上传进度反馈

使用流程

获取上传策略 (OssUploadPolicy)
初始化 Storage 和 PutController
配置上传参数 (PutOptions)
执行文件上传 (storage.putFile)
处理上传结果

注意事项

确保上传的文件路径正确
处理上传过程中的各种状态（成功、失败、进度等）
及时清理未成功上传的文件
遵守七牛云的使用规范和政策

总结

qiniu_flutter_sdk 为项目提供了稳定可靠的图片上传功能，极大地简化了图片管理的复杂度，提升了用户体验。通过合理的配置和优化，可以充分发挥SDK的性能，为应用提供高效的文件存储解决方案。