@minto-ai/aws-obs-server/README.md

亚马逊OBS文件上传

本工具库用于处理文件上传至亚马逊 OBS（对象存储服务），支持单文件上传和分片上传两种方式，能满足不同大小文件的上传需求。

# 安装

使用 `pnpm` 进行安装：

```bash
pnpm install @minto-ai/aws-obs-server
```

# 使用

## 示例代码

```js
import awsObsServer from '@minto-ai/aws-obs-server'

// 配置全局参数
awsObsServer.config({
  getToken: () => '用户的token',
  fileSplitThreshold: 1024 * 1024 * 5
})

// 创建要上传的文件对象
const sourceFile = new File(['hello world'], 'hello.txt', { type: 'text/plain' })

// 创建上传实例
const uploadContext = awsObsServer.create({
  sourceFile,
  onProgress: (event) => {
    console.log(`Upload progress: ${event.percent}%`)
  },
  onSuccess: (event) => {
    console.log('Upload success:', event.fileInfo)
  }
})

// 取消上传示例
// uploadContext.abort()

```

## 全局配置

全局配置可通过 `awsObsServer.config` 方法进行设置，支持以下参数：

| 参数                 | 类型           | 必填 | 默认值                      | 描述                                                                                               |
| -------------------- | -------------- | ---- | --------------------------- | -------------------------------------------------------------------------------------------------- |
| `getToken`           | `() => string` | 是   | 无                          | 用于获取上传所需的 token，该 token 用于身份验证，确保上传请求的合法性。                            |
| `fileSplitThreshold` | `number`       | 否   | `1024*1024*5`（单位为字节） | 单文件上传和分片上传的文件大小分隔线。当文件大小超过该阈值时，将使用分片上传；否则使用单文件上传。 |

## 上传选项

创建上传实例时，可通过 `awsObsServer.create` 方法传入上传选项，支持以下参数：

| 参数         | 类型                                                                      | 必填 | 默认值                      | 描述                                                                                         |
| ------------ | ------------------------------------------------------------------------- | ---- | --------------------------- | -------------------------------------------------------------------------------------------- |
| `sourceFile` | `File`                                                                    | 是   | 无                          | 要上传的文件对象。                                                                           |
| `partSize`   | `number`                                                                  | 否   | `1024*1024*5`（单位为字节） | 文件分片大小。                                                                               |
| `onStart`    | `() => void`                                                              | 否·  | `() => {}`                  | 上传开始时的回调函数。                                                                       |
| `onProgress` | `(event: { percent: number }) => void`                                    | 否   | `() => {}`                  | 上传进度回调函数，`event.percent` 表示上传进度百分比。                                       |
| `onSuccess`  | `(event: { sourceFile: File, fileInfo: IUploadFileSuccessFile }) => void` | 否   | `() => {}`                  | 上传成功时的回调函数，`event.sourceFile` 为上传的文件对象，`event.fileInfo` 为文件上传信息。 |
| `onError`    | `(error: Error) => void`                                                  | 否   | `() => {}`                  | 上传失败时的回调函数，`error` 为`ObsError`错误对象。                                         |
| `onAbort`    | `() => void`                                                              | 否   | `() => {}`                  | 取消上传时的回调函数。                                                                       |
| `onFinally`  | `() => void`                                                              | 否   | `() => {}`                  | 上传结束时的回调函数，无论上传成功或失败都会触发。                                           |

## 取消上传

可通过调用上传实例的 `abort` 方法取消上传：

```js
uploadContext.abort()
```

## 错误处理

工具库中定义了多种错误码，当上传过程中出现错误时，会抛出对应的 `ObsError` 对象，可通过 `error.code` 获取错误码，根据错误码进行相应的处理。错误码及其含义如下：

| 错误码  | 描述                                                  |
| ------- | ----------------------------------------------------- |
| `10001` | 请求失败，请检查网络                                  |
| `10022` | 切片上传文件初始化信息的临时 URL 获取失败，请检查网络 |
| `10002` | 切片上传文件初始化信息获取失败，请检查文件            |
| `10033` | 切片上传文件段的临时 URL 获取失败，请检查网络         |
| `10003` | 切片上传文件段失败，请检查文件                        |
| `10055` | 合并文件段的临时 URL 获取失败，请检查网络             |
| `10005` | 合并文件段失败，请检查文件                            |
| `10006` | 获取文件信息失败，请检查网络                          |
| `10009` | 单文件上传获取临时 URL 失败，请检查网络               |
| `10099` | 单文件上传失败，请检查文件                            |
| `10007` | 文件上传取消失败，请检查网络                          |

# 注意事项

- 本工具库依赖 `axios`，请确保项目中已安装 `axios`，版本要求为 `^1.7.9`。
- 在使用 `getToken` 方法获取 token 时，请确保返回的 token 是有效的，否则可能导致上传失败。
- 上传大文件时，建议根据网络状况和服务器性能调整 `partSize` 和 `fileSplitThreshold` 参数，以提高上传效率。