# oss_dart

**Repository Path**: hsxr/oss_dart

## Basic Information

- **Project Name**: oss_dart
- **Description**: 阿里云oss-dart-API
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-07-07
- **Last Updated**: 2025-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# oss_dart V2

A Flutter package for Alibaba Cloud Object Storage Service (OSS) with dual authentication support and null safety.

[![pub package](https://img.shields.io/pub/v/oss_dart.svg)](https://pub.dev/packages/oss_dart)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features V2

- ✅ **Dual Authentication Support** - Both STS and direct AccessKey authentication
- ✅ **Null safety support** - Complete null safety compliance
- ✅ **Upload files to OSS** - Memory data and local files
- ✅ **Download files from OSS** - Memory and local file download
- ✅ **Delete files from OSS** - Simple file deletion (direct auth)
- ✅ **Multipart upload for large files** - Efficient large file handling
- ✅ **STS authentication** - Secure temporary credentials
- ✅ **Direct authentication** - Simple AccessKey/Secret authentication
- ✅ **Backward compatibility** - Legacy constructor support
- ✅ **Comprehensive error handling** - Robust error management
- ✅ **Modern Flutter/Dart compatibility** - Latest SDK support

## Installation

Add this to your package's `pubspec.yaml` file:

```yaml
dependencies:
  oss_dart: ^2.0.0
```

Then run:

```bash
flutter pub get
```

## Getting Started

### 1. STS Authentication (Recommended for Production)

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

// Create OSS client with STS authentication
OssClient client = OssClient.sts(
  bucketName: 'your-bucket-name',
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  tokenGetter: getStsAccount,
);

// Check if file exists
bool exists = await client.objectExists('path/to/your/file.txt');
print('File exists: $exists');

// Get file metadata
if (exists) {
  var metaResponse = await client.getObjectMeta('path/to/your/file.txt');
  print('File size: ${metaResponse.headers['content-length']} bytes');
  print('Content type: ${metaResponse.headers['content-type']}');
}

// Upload file
List<int> fileData = [/* your file data */];
String fileKey = 'path/to/your/file.txt';
var response = await client.putObject(fileData, fileKey);

// Download file
var response = await client.getObject(fileKey);
String content = response.body;
```

### 2. Direct Authentication (Simple for Development)

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

// Create OSS client with direct authentication
OssClient client = OssClient.direct(
  bucketName: 'your-bucket-name',
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  directAccessKey: 'your-access-key',
  directAccessSecret: 'your-access-secret',
);

// Upload file from memory
var response = await client.putObject(fileData, fileKey);

// Upload local file (V2 feature)
var response = await client.uploadFile('/path/to/local/file.txt', 'remote/file.txt');

// Delete file (V2 feature)
var response = await client.deleteObject(fileKey);
```

### 3. Legacy Constructor (Backward Compatibility)

```dart
// Still works for existing code
OssClient client = OssClient(
  bucketName: 'your-bucket-name',
  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
  tokenGetter: getStsAccount,
);
```

### 4. STS Token Implementation

You need to implement a function that returns STS credentials:

```dart
Future<Map<String, dynamic>> getStsAccount() async {
  // Call your backend service to get STS credentials
  return {
    'AccessKeyId': 'your-sts-access-key-id',
    'AccessKeySecret': 'your-sts-access-key-secret',
    'SecurityToken': 'your-sts-security-token',
    'Expiration': '2024-12-31T23:59:59Z',
  };
}
```

### 3. Multipart Upload (for large files)

```dart
// Initialize multipart upload
var initResponse = await client.initiateMultipartUpload(fileKey);

// Upload parts
List<String> etags = [];
for (int i = 0; i < parts.length; i++) {
  var partResponse = await client.uploadPart(
    parts[i],
    fileKey,
    uploadId,
    i + 1
  );
  etags.add(partResponse.headers['etag']!);
}

// Complete multipart upload
await client.completeMultipartUpload(etags, fileKey, uploadId);
```

## API Reference

### OssClient

#### Constructor

- `OssClient({String? endpoint, String bucketName, Function? tokenGetter, String? proxy})`

#### Methods

- `Future<bool> objectExists(String fileKey)` - Check if a file exists in OSS
- `Future<http.Response> getObjectMeta(String fileKey)` - Get file metadata without downloading content
- `Future<http.Response> putObject(List<int> fileData, String fileKey, [Map<String, String>? header])` - Upload a file
- `Future<http.Response> getObject(String fileKey)` - Download a file
- `Future<Response> downloadObject(String fileKey, String savePath)` - Download large file to local path
- `Future<http.Response> uploadFile(String filePath, String fileKey)` - Upload local file (direct auth only)
- `Future<http.Response> deleteObject(String fileKey)` - Delete a file (direct auth only)
- `Future<http.Response> initiateMultipartUpload(String fileKey)` - Initialize multipart upload
- `Future<http.Response> uploadPart(List<int> fileData, String fileKey, String uploadId, num partNum)` - Upload a part
- `Future<http.Response> completeMultipartUpload(List<String> etags, String fileKey, String uploadId)` - Complete multipart upload
- `Future<http.Response> listParts(String fileKey, String uploadId)` - List uploaded parts

## Requirements

- Flutter >= 3.0.0
- Dart >= 3.0.0

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## References

- [Alibaba Cloud OSS Documentation](https://www.alibabacloud.com/help/en/object-storage-service)
- [OSS API Reference](https://www.alibabacloud.com/help/en/object-storage-service/latest/api-reference)