# YX OSS

[![pub package](https://img.shields.io/pub/v/yx_oss.svg)](https://pub.dev/packages/yx_oss)
[![documentation](https://img.shields.io/badge/documentation-latest-brightgreen.svg)](https://pub.dev/documentation/yx_oss/latest/)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

一个专注于核心功能的阿里云 OSS (Object Storage Service) Flutter 客户端库，提供纯净的文件上传下载能力。

## 🎯 设计理念

**单一职责**：本库专注于 OSS 核心操作 - 文件上传、下载和管理。故意排除了 UI 组件、图片压缩、文件选择等功能，保持简洁性和灵活性。

**最小依赖**：仅包含 OSS 操作的必需依赖，让您可以自由选择自己的 UI 和工具库。

## ✨ 核心特性

### 认证与配置
- 🔐 **多种认证方式**：静态密钥、STS临时凭证、预签名URL
- ⚙️ **动态配置**：运行时配置更新和缓存
- 🔌 **可插拔提供者**：灵活的认证和配置提供者架构

### 上传与下载
- 📤 **断点续传**：支持大文件的断点续传，本地存储断点信息
- 🧩 **分片上传**：大文件自动分片处理，支持并发上传
- 📊 **进度监控**：实时上传下载进度跟踪
- ⚡ **预签名URL**：支持客户端直接上传，服务端控制权限

### 可靠性与错误处理
- 🔄 **重试机制**：指数退避重试失败操作
- 🛡️ **类型安全错误处理**：完整的错误类型和处理
- ❌ **取消支持**：可取消正在进行的操作
- 📝 **统一日志**：可配置的日志系统，支持自定义处理器

### 架构特点
- 🎯 **零耦合**：不依赖特定项目架构
- 📱 **跨平台**：支持 iOS、Android、Web、Desktop
- 🏗️ **清洁架构**：依赖注入和关注点分离
- 🔧 **项目集成**：提供现成的项目集成适配器

## 🚀 快速开始

### 安装

在你的 `pubspec.yaml` 文件中添加依赖：

```yaml
dependencies:
  yx_oss: ^1.0.0
```

然后运行：

```bash
flutter pub get
```

### 基础用法

```dart
import 'package:yx_oss/yx_oss.dart';

// 1. 创建认证提供者
final authProvider = StaticAuthProvider(
  accessKeyId: 'your_access_key_id',
  accessKeySecret: 'your_access_key_secret',
);

// 2. 创建配置提供者
final configProvider = StaticConfigProvider(
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  bucketName: 'your-bucket-name',
  directory: 'uploads',
);

// 3. 创建客户端配置
final config = YxOSSConfig(
  authProvider: authProvider,
  configProvider: configProvider,
  logConfig: LogConfig(
    enabled: true,
    level: LogLevel.info,
    logError: true,
  ),
);

// 4. 创建OSS客户端
final client = YxOSSClient(config);

// 5. 初始化客户端
await client.initialize();

// 6. 上传文件
final fileData = Uint8List.fromList('Hello, World!'.codeUnits);
final result = await client.uploadBytes(
  fileData,
  'my-file.txt',
  options: UploadOptions(
    callbacks: UploadCallbacks(
      onProgress: (sent, total) {
        print('进度: ${(sent / total * 100).toStringAsFixed(1)}%');
      },
      onSuccess: (result) {
        print('上传成功: ${result.url}');
      },
    ),
  ),
);

// 7. 释放资源
client.dispose();
```

## 📖 详细文档

### 认证方式

#### 1. 静态认证 (Static Authentication)

适用于开发测试环境或简单应用场景：

```dart
final authProvider = StaticAuthProvider(
  accessKeyId: 'your_access_key_id',
  accessKeySecret: 'your_access_key_secret',
);
```

#### 2. STS临时凭证 (STS Authentication)

适用于生产环境，提供更安全的权限控制：

```dart
// 从服务器获取STS凭证的函数
Future<STSCredentials> getSTSCredentials() async {
  // 调用你的后端API获取STS凭证
  final response = await http.get('/api/sts-credentials');
  return STSCredentials.fromJson(response.data);
}

final authProvider = STSAuthProvider(
  accessKeyId: stsCredentials.accessKeyId,
  accessKeySecret: stsCredentials.accessKeySecret,
  securityToken: stsCredentials.securityToken,
  expiration: stsCredentials.expiration,
  credentialsGetter: getSTSCredentials, // 自动刷新过期凭证
);
```

#### 3. 项目集成认证 (Project Integration)

适用于现有项目集成，从后端API获取配置：

```dart
// 使用项目集成适配器
final manager = ProjectOSSManager(myApiImpl);
await manager.initialize();

// 直接使用，自动处理认证和配置
final fileUrl = await manager.uploadFile(
  filePath,
  onProgress: (sent, total) => print('进度: $sent/$total'),
  type: 1, // 文件类型
);
```

### 配置管理

#### 1. 静态配置 (Static Configuration)

```dart
final configProvider = StaticConfigProvider(
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  bucketName: 'your-bucket-name',
  directory: 'uploads',
  domain: 'https://your-custom-domain.com', // 可选
);
```

#### 2. 动态配置 (Dynamic Configuration)

支持从服务器动态获取配置，适用于多环境部署：

```dart
final configProvider = DynamicConfigProvider(
  configGetter: () async {
    final response = await http.get('/api/oss-config');
    return OSSConfig.fromJson(response.data);
  },
  cacheTimeout: const Duration(hours: 1), // 配置缓存时间
);
```

### 日志配置

新增统一的日志系统，支持级别控制和自定义处理器：

```dart
final config = YxOSSConfig(
  authProvider: authProvider,
  configProvider: configProvider,
  logConfig: LogConfig(
    enabled: true,
    level: LogLevel.warning,    // 只记录警告及以上级别
    logRequest: false,          // 是否记录HTTP请求
    logResponse: false,         // 是否记录HTTP响应
    logError: true,             // 是否记录错误
    customHandler: (message, level) {
      // 自定义日志处理，可接入你的日志系统
      myLogger.log(level.name, message);
    },
  ),
);
```

### 上传选项

```dart
final options = UploadOptions(
  // 基础选项
  overwrite: true,                    // 是否覆盖同名文件
  contentType: 'image/jpeg',          // 文件MIME类型
  enableResume: true,                 // 启用断点续传

  // 访问控制
  acl: ACLMode.publicRead,            // 访问权限
  storageClass: StorageClass.standard, // 存储类型

  // 自定义元数据
  metadata: {
    'author': 'YX OSS',
    'version': '1.0.0',
  },

  // 分片上传配置
  enableMultipart: true,              // 启用分片上传
  partSize: 10 * 1024 * 1024,         // 分片大小 (10MB)
  multipartThreshold: 100 * 1024 * 1024, // 分片阈值 (100MB)
  concurrency: 3,                     // 并发上传数

  // 回调函数
  callbacks: UploadCallbacks(
    onStart: () => print('开始上传'),
    onProgress: (sent, total) {
      final progress = (sent / total * 100).toStringAsFixed(1);
      print('上传进度: $progress%');
    },
    onSuccess: (result) => print('上传成功: ${result.url}'),
    onError: (error) => print('上传失败: ${error.message}'),
    onComplete: () => print('上传完成'),
  ),
);
```

### 断点续传

支持大文件的断点续传功能：

```dart
// 启用断点续传的上传
final result = await client.uploadFile(
  largeFilePath,
  options: UploadOptions(
    enableResume: true,
    callbacks: UploadCallbacks(
      onProgress: (sent, total) {
        print('断点续传进度: ${(sent/total*100).toInt()}%');
      },
    ),
  ),
);

// 获取可恢复的上传任务
final resumableTasks = await client.getResumableTasks();
for (final task in resumableTasks) {
  print('可恢复任务: ${task.objectKey}, 进度: ${task.uploadedSize}/${task.totalSize}');
}

// 恢复指定任务
final resumeResult = await client.resumeUpload(taskId);

// 清理过期的断点续传数据
await client.cleanupExpiredData(maxAgeDays: 7);
```

### 错误处理

库提供了完整的错误类型定义：

```dart
try {
  final result = await client.uploadBytes(data, 'file.txt');
  print('上传成功: ${result.url}');
} catch (e) {
  if (e is OSSError) {
    switch (e.type) {
      case OSSErrorType.network:
        print('网络错误: ${e.message}');
        break;
      case OSSErrorType.authentication:
        print('认证错误: ${e.message}');
        break;
      case OSSErrorType.permission:
        print('权限错误: ${e.message}');
        break;
      case OSSErrorType.server:
        print('服务器错误: ${e.message}');
        break;
      default:
        print('其他错误: ${e.message}');
    }

    // 检查是否可重试
    if (e.isRetryable) {
      print('此错误可以重试');
    }
  }
}
```

## 🔧 高级配置

### 完整配置示例

```dart
final config = YxOSSConfig(
  authProvider: authProvider,
  configProvider: configProvider,

  // 超时配置
  timeoutConfig: TimeoutConfig(
    connectTimeout: 30000,    // 30秒连接超时
    sendTimeout: 600000,      // 10分钟发送超时
    receiveTimeout: 600000,   // 10分钟接收超时
  ),

  // 重试配置
  retryConfig: RetryConfig(
    maxRetries: 5,                    // 最多重试5次
    initialInterval: 500,             // 初始间隔500ms
    backoffMultiplier: 2.0,           // 指数退避因子
    maxInterval: 30000,               // 最大间隔30秒
    enableExponentialBackoff: true,   // 启用指数退避
  ),

  // 日志配置
  logConfig: LogConfig(
    enabled: true,
    level: LogLevel.debug,
    logRequest: true,       // 记录请求详情
    logResponse: true,      // 记录响应详情
    logError: true,         // 记录错误详情
    customHandler: (message, level) {
      // 自定义日志处理
      print('[YX_OSS] ${level.name.toUpperCase()}: $message');
    },
  ),
);
```

## 🏗️ 项目集成

### 使用项目集成适配器

库提供了现成的项目集成适配器，可以快速集成到现有项目中：

```dart
// 1. 实现服务器API接口
class MyOSSApiImpl implements YxOssServerInterface {
  @override
  Future<YxOSSConfigModel> getOssConfig() async {
    // 从你的后端获取OSS配置
    final response = await http.get('/api/oss-config');
    return YxOSSConfigModel.fromJson(response.data);
  }

  @override
  Future<YxOSSSignModel> getOssSign({String? objectName, int? type}) async {
    // 从你的后端获取预签名URL
    final response = await http.post('/api/oss-sign', {
      'objectName': objectName,
      'type': type,
    });
    return YxOSSSignModel.fromJson(response.data);
  }

  @override
  Future<bool> deleteOSSFile({required String filePath}) async {
    // 删除文件
    final response = await http.delete('/api/oss-file', {
      'filePath': filePath,
    });
    return response.statusCode == 200;
  }
}

// 2. 使用项目集成管理器
final ossManager = ProjectOSSManager(MyOSSApiImpl());
await ossManager.initialize();

// 3. 上传文件（自动使用预签名URL）
final fileUrl = await ossManager.uploadFile(
  filePath,
  onProgress: (sent, total) {
    print('上传进度: ${(sent/total*100).toInt()}%');
  },
  type: 1, // 文件类型：1-普通上传，2-资料收集等
);

// 4. 上传字节数组
final fileUrl = await ossManager.uploadBytes(
  fileBytes,
  'example.jpg',
  onProgress: (sent, total) => print('进度: $sent/$total'),
  type: 1,
);

// 5. 删除文件
final success = await ossManager.deleteFile(fileUrl);

// 6. 断点续传相关
final tasks = await ossManager.getResumableTasks();
final resumeResult = await ossManager.resumeUpload(taskId);
await ossManager.cleanupExpiredData(maxAgeDays: 7);
```

### 集成到应用生命周期

```dart
class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late final ProjectOSSManager ossManager;

  @override
  void initState() {
    super.initState();
    ossManager = ProjectOSSManager(MyOSSApiImpl());
  }

  Future<void> initializeOSS() async {
    try {
      await ossManager.initialize();
      print('OSS初始化成功');
    } catch (e) {
      print('OSS初始化失败: $e');
    }
  }

  @override
  void dispose() {
    ossManager.dispose();
    super.dispose();
  }

  // ... 其他代码
}
```

## 🌍 区域支持

库内置了常用的阿里云OSS区域配置：

```dart
// 中国大陆区域
CommonRegions.hangzhou    // 华东1 (杭州)
CommonRegions.beijing     // 华北2 (北京)
CommonRegions.shanghai    // 华东2 (上海)
CommonRegions.shenzhen    // 华南1 (深圳)
CommonRegions.chengdu     // 西南1 (成都)

// 海外区域
CommonRegions.singapore   // 亚太东南1 (新加坡)
CommonRegions.sydney      // 亚太东南2 (悉尼)
CommonRegions.tokyo       // 亚太东北1 (东京)
CommonRegions.virginia    // 美国东部1 (弗吉尼亚)
CommonRegions.london      // 欧洲西部1 (伦敦)
```

## 🔄 迁移指南

### 从Legacy OSS迁移

如果你正在从现有的OSS实现迁移到YX OSS：

#### 原项目代码
```dart
// 原项目可能是这样的
final ossClient = AliyunOssClientUtils();
await ossClient.uploadFile(file, fileName);
```

#### YX OSS代码
```dart
// 迁移到YX OSS - 使用项目集成适配器
final ossManager = ProjectOSSManager(apiImpl);
await ossManager.initialize();
final fileUrl = await ossManager.uploadFile(filePath);
```

#### 迁移优势

1. **解耦合**: YX OSS是完全独立的库，不依赖项目特定的代码
2. **更好的错误处理**: 类型安全的错误处理机制
3. **断点续传**: 完整的断点续传支持
4. **灵活配置**: 支持多种认证和配置方式
5. **统一日志**: 可配置的日志系统
6. **更好的测试**: 所有组件都可以独立测试

## 📚 API文档

### 核心类

- `YxOSSClient` - OSS客户端主类
- `YxOSSConfig` - 客户端配置
- `ProjectOSSManager` - 项目集成管理器

### 接口

- `AuthProvider` - 认证提供者接口
- `ConfigProvider` - 配置提供者接口
- `ResumeStorage` - 断点续传存储接口
- `YxOssServerInterface` - 服务器API接口

### 模型

- `UploadOptions` - 上传选项
- `UploadResult` - 上传结果
- `OSSError` - 错误类型

### 工具

- `YxOSSFileUtils` - 文件工具类
- `OssLogger` - 日志工具

## 🧪 测试

```dart
// 运行测试
flutter test

// 运行集成测试
flutter test integration_test/
```



### 开发环境设置

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 创建 Pull Request



## 📈 更新日志

### v1.0.0
- ✅ 核心OSS上传下载功能
- ✅ 多种认证方式支持
- ✅ 断点续传功能
- ✅ 项目集成适配器
- ✅ 统一日志系统
- ✅ 完整的错误处理
- ✅ 类型安全的API设计

---

**YX OSS** - 让 Flutter OSS 上传更简单、更可靠！ 🚀