@mt-utils/huawei-obs/README.md

华为云OBS文件上传下载

# @mt-utils/huawei-obs

华为云OBS文件上传下载工具库，用于处理文件的分片上传和下载。

## 特点

- 提供灵活的参数配置，包括分片大小、上传目录等。
- 支持使用默认参数或部分覆盖以简化配置流程。
- 支持分片上传，提高大文件上传的稳定性和效率。
- 提供详细的错误码和回调事件，便于调试和监控上传进度。

## 安装

```bash
pnpm install @mt-utils/huawei-obs
```

## 使用方法

### 初始化配置

```js
import huaweiBbs from '@mt-utils/huawei-obs'

/**
 * 华为云OBS平台系统配置
 */
const systemConfig = {
  /**
   * OBS为每个区域提供了一个Endpoint，用于处理该区域的访问请求
   * @required
   */
  ENDPOINT: 'your_endpoint',
  /**
   * 在华为云平台申请的密钥ID
   * @required
   */
  ACCESS_KEY_ID: 'your_access_key_id',
  /**
   * 与ACCESS_KEY_ID对应的密钥信息
   * @required
   */
  SECRET_ACCESS_KEY: 'your_secret_access_key',
  /**
   * OBS桶的名称
   * @required
   */
  BUCKET_NAME: 'your_bucket_name'
}

// 配置系统参数
huaweiBbs.config(systemConfig)
```

### 执行分片上传

```javascript
// 所需上传的文件
const file = new File(['hello world'], 'hello.txt', { type: 'text/plain' })

/**
 * 分片上传选项
 */
const sliceUploadOptions = {
  /**
   * 文件分片大小，单位为字节
   * @default 1024 * 1024 * 5
   * @optional
   */
  partSize: 1024 * 1024 * 5,
  /**
   * 上传开始回调
   * @optional
   */
  onStart: () => {
    console.log('Upload started')
  },
  /**
   * 上传进度回调
   * @param event - 包含上传进度信息的对象
   * @param event.percent - 上传进度百分比
   * @optional
   */
  onProgress: (event) => {
    console.log(`Upload progress: ${event.percent}%`)
  },
  /**
   * 上传成功回调
   * @param event - 包含上传结果信息的对象
   * @param event.sourceFile - 文件对象
   * @param event.fileDir - 文件上传目录
   * @optional
   */
  onSuccess: (event) => {
    console.log('Upload success:', event)
  },
  /**
   * 上传失败回调
   * @param error - 错误对象，可能是标准 Error 对象或自定义 ObsError 对象
   * @optional
   */
  onError: (error) => {
    console.error('Upload error:', error)
  },
  /**
   * 取消上传回调
   * @optional
   */
  onAbort: () => {
    console.log('Upload aborted')
  },
  /**
   * 上传结束回调，无论成功或失败都会触发
   * @optional
   */
  onFinally: () => {
    console.log('Upload finished')
  }
}

// 执行分片上传
const sliceUpload = huaweiBbs.createUploadContext(file).createSliceUpload(sliceUploadOptions)

// 取消分片上传
sliceUpload.abort()
```

## 错误码

以下是华为云OBS工具库定义的错误码及其描述：

| 错误码               | 代码                        | 描述    |
| :------------------- | :-------------------------- | :------ |
| 请求失败，请检查网络 | `UPLOAD_NETWORK_ERROR`      | `10001` |
| 切片上传初始化失败   | `SLICE_UPLOAD_INIT_ERROR`   | `10002` |
| 文件切片上传失败     | `SLICE_UPLOAD_UPLOAD_ERROR` | `10003` |
| 切片合并失败         | `SLICE_UPLOAD_MERGE_ERROR`  | `10005` |
| 取消分段上传任务失败 | `SLICE_UPLOAD_ABORT_ERROR`  | `10006` |