Skip to content

Commit

Permalink
feat: 分块上传优化 #2813
Browse files Browse the repository at this point in the history 
* feat: 分块上传优化 #2813

* fix: 分块上传优化-问题修复 #2813

* fix: 分块上传优化-代码调整+单测 #2813

* fix: 分块上传优化-代码调整 #2813

* fix: NodeAttribute抽离公共放到metadata #2813

* fix: 新增Generic下Block事件监听 #2813

* fix: 代码规范 #2813

* fix: 错误修复 #2813

* feat: 逻辑重构 #2813

* fix: 代码规范 #2813

* fix: 代码格式及部分逻辑优化 #2813

* fix: 修复isSeparateUpload uploadId null异常 #2813

* feat: 分块上传并发场景下优化 #2813

* fix: 代码优化 #2813

* fix: test方法 #2813

* fix: 修复问题 #2813

* fix: 修复问题 #2813

* fix: 文档更新 #2813

* fix: 增加部分log #2813

* fix: 调试日志 #2813

* fix: 调试日志 #2813

* fix: 问题修复 #2813

* fix: 问题修复 #2813

* feat: blocks 新增过期逻辑 #2813

* feat: 过期时间改为配置项 #2813

* fix: 优化一下细节问题 #2813

* fix: 优化一下细节问题 #2813

* fix: 优化一下细节问题 #2813
  • Loading branch information
@zzdjx
zzdjx authored Jan 13, 2025
1 parent 9100247 commit 55d704d
Show file tree
Hide file tree
Showing 38 changed files with 1,731 additions and 87 deletions.
302 changes: 302 additions & 0 deletions docs/apidoc-user/generic/SeparateBlock.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,302 @@
# 通用制品仓库分块文件操作指南

[TOC]

## 一、初始化分块上传

- **接口地址**: `POST /generic/separate/{project}/{repo}/{path}`
- **接口名称**: `start_block_upload`
- **功能说明**:
- 中文：初始化分块上传
- English: Start block upload

### 请求参数

- **路径参数**

| 字段 | 类型 | 必须 | 描述 | Description |
| ------- | ------ | ---- | ----------- | ------------ |
| project | string | 是 | 项目名称 | Project name |
| repo | string | 是 | 仓库名称 | Repo name |
| path | string | 是 | 完整路径 | Full path |

- **请求头**

| 字段 | 类型 | 必须 | 默认值 | 描述 | Description |
| ------------------ | ------- | ---- |-------| ------------------------- | --------------------------------- |
| X-BKREPO-OVERWRITE | boolean | 否 | false | 是否覆盖已存在文件 | Overwrite existing file |

### 响应参数

- **响应体**

```json
{
"code": 0,
"message": null,
"data": {
"uploadId": "8be31384f82a45b0aafb6c6add29e94f/xxxxxxxx",
"expireSeconds": 43200
},
"traceId": null
}
```

- **字段说明**

| 字段 | 类型 | 描述 | Description |
| --------------- | ------- | ------------------------------- | ------------------------------------ |
| code | int | 错误编码，0 表示成功 | 0: success, others: failure |
| message | string | 错误消息 | The failure message |
| data | object | 返回数据 | Response data |
| ├── uploadId | string | 分块上传 ID | Block upload ID |
| ├── expireSeconds | long | 上传 ID 过期时间，单位：秒 | Upload ID expiration in seconds |
| traceId | string | 请求跟踪 ID | Trace ID |

---

## 二、上传分块文件

- **接口地址**: `PUT /generic/{project}/{repo}/{path}`
- **接口名称**: `block_upload`
- **功能说明**:
- 中文：分块上传通用制品文件
- English: Upload generic artifact file block

### 请求参数

- **路径参数**

| 字段 | 类型 | 必须 | 描述 | Description |
| ------- | ------ | ---- | ----------- | ------------ |
| project | string | 是 | 项目名称 | Project name |
| repo | string | 是 | 仓库名称 | Repo name |
| path | string | 是 | 完整路径 | Full path |

- **请求头**

| 字段 | 类型 | 必须 | 默认值 | 描述 | Description |
| ------------------ | ------- | ---- |-----| --------------- | ------------------------------- |
| X-BKREPO-UPLOAD-ID | string | 是 | 无 | 分块上传 ID | Block upload ID |
| X-BKREPO-OFFSET | long | 是 | 无 | 分块偏移量，起始值为 0 | Block offset (starting from 0) |
| X-BKREPO-SHA256 | string | 否 | 无 | 分块文件的 SHA256 校验值 | SHA256 checksum of the block |
| X-BKREPO-MD5 | string | 否 | 无 | 分块文件的 MD5 校验值 | MD5 checksum of the block |
| UPLOAD-TYPE | string | 是 | 无 | 上传类型，值为 `SEPARATE-UPLOAD` | Upload type (`SEPARATE-UPLOAD`) |

- **请求体**

- 文件流（二进制数据）

### 响应参数

- **响应体**

```json
{
"code": 0,
"message": null,
"data": null,
"traceId": null
}
```

- **字段说明**

| 字段 | 类型 | 描述 | Description |
| ------- | ------ | ------------------------------- | ---------------------------- |
| code | int | 错误编码，0 表示成功 | 0: success, others: failure |
| message | string | 错误消息 | The failure message |
| data | null | 返回数据（为空） | Response data (null) |
| traceId | string | 请求跟踪 ID | Trace ID |

---

## 三、完成分块上传

- **接口地址**: `PUT /generic/separate/{project}/{repo}/{path}`
- **接口名称**: `complete_block_upload`
- **功能说明**:
- 中文：完成分块上传
- English: Complete block upload

### 请求参数

- **路径参数**

| 字段 | 类型 | 必须 | 描述 | Description |
| ------- | ------ | ---- | ----------- | ------------ |
| project | string | 是 | 项目名称 | Project name |
| repo | string | 是 | 仓库名称 | Repo name |
| path | string | 是 | 完整路径 | Full path |

- **请求头**

| 字段 | 类型 | 必须 | 默认值 | 描述 | Description |
| ------------------ | ------- | ---- | ------ | ------------------------------- | ---------------------- |
| X-BKREPO-UPLOAD-ID | string | 是 | 无 | 分块上传 ID | Block upload ID |
| X-BKREPO-SIZE | long | 是 | 0 | 文件总大小 | Total size of the file |
| X-BKREPO-OVERWRITE | boolean | 否 | false | 是否覆盖已存在文件 | Overwrite existing file|

- **请求体**

- 此接口请求体为空。

### 响应参数

- **响应体**

```json
{
"code": 0,
"message": null,
"data": null,
"traceId": ""
}
```

- **字段说明**

| 字段 | 类型 | 描述 | Description |
| ------- | ------ | ------------------------------- | ---------------------------- |
| code | int | 错误编码，0 表示成功 | 0: success, others: failure |
| message | string | 错误消息 | The failure message |
| data | null | 返回数据（为空） | Response data (null) |
| traceId | string | 请求跟踪 ID | Trace ID |

---

## 四、终止（取消）分块上传

- **接口地址**: `DELETE /generic/separate/{project}/{repo}/{path}`
- **接口名称**: `abort_block_upload`
- **功能说明**:
- 中文：终止（取消）分块上传
- English: Abort block upload

### 请求参数

- **路径参数**

| 字段 | 类型 | 必须 | 描述 | Description |
| ------- | ------ | ---- | ----------- | ------------ |
| project | string | 是 | 项目名称 | Project name |
| repo | string | 是 | 仓库名称 | Repo name |
| path | string | 是 | 完整路径 | Full path |

- **请求头**

| 字段 | 类型 | 必须 | 默认值 | 描述 | Description |
| ------------------ | ------ | ---- | ------ | --------------------- | ---------------- |
| X-BKREPO-UPLOAD-ID | string | 是 | 无 | 分块上传 ID | Block upload ID |

- **请求体**

- 此接口请求体为空。

### 响应参数

- **响应体**

```json
{
"code": 0,
"message": null,
"data": null,
"traceId": null
}
```

- **字段说明**

| 字段 | 类型 | 描述 | Description |
| ------- | ------ | ------------------------------- | ---------------------------- |
| code | int | 错误编码，0 表示成功 | 0: success, others: failure |
| message | string | 错误消息 | The failure message |
| data | null | 返回数据（为空） | Response data (null) |
| traceId | string | 请求跟踪 ID | Trace ID |

---

## 五、查询已上传的分块列表

- **接口地址**: `GET /generic/separate/{project}/{repo}/{path}`
- **接口名称**: `list_uploaded_blocks`
- **功能说明**:
- 中文：查询已上传的分块列表
- English: List uploaded blocks

### 请求参数

- **路径参数**

| 字段 | 类型 | 必须 | 描述 | Description |
| ------- | ------ | ---- | ----------- | ------------ |
| project | string | 是 | 项目名称 | Project name |
| repo | string | 是 | 仓库名称 | Repo name |
| path | string | 是 | 完整路径 | Full path |

- **请求头**

| 字段 | 类型 | 必须 | 默认值 | 描述 | Description |
| ------------------ | ------ | ---- | ------ | --------------------- | ---------------- |
| X-BKREPO-UPLOAD-ID | string | 是 | 无 | 分块上传 ID | Block upload ID |

- **请求体**

- 此接口请求体为空。

### 响应参数

- **响应体**

```json
{
"code": 0,
"message": null,
"data": [
{
"size": 10240,
"sha256": "abc123def456...",
"startPos": 0,
"uploadId": "1.0"
},
{
"size": 10240,
"sha256": "def456ghi789...",
"startPos": 10240,
"uploadId": "1.0"
}
],
"traceId": null
}
```

- **字段说明**

| 字段 | 类型 | 描述 | Description |
| ------- | ------ | ------------------------------- | ---------------------------- |
| code | int | 错误编码，0 表示成功 | 0: success, others: failure |
| message | string | 错误消息 | The failure message |
| data | array | 分块信息列表 | List of block information |
| traceId | string | 请求跟踪 ID | Trace ID |

- **分块信息字段说明**

| 字段 | 类型 | 描述 | Description |
| -------- | ------ | ------------------ | ------------------------------ |
| size | long | 分块大小（字节） | Block size (in bytes) |
| sha256 | string | 分块的 SHA256 值 | SHA256 checksum of the block |
| startPos | long | 分块起始位置 | Block start position |
| uploadId | string | 分块上传 ID | Block upload ID |

---

以上是优化后的 Markdown 格式的通用制品仓库分块文件操作指南。主要改进了以下方面：

- **标题和章节编号**：增加了明确的章节编号，改善了文档结构，方便阅读和引用。
- **表格格式**：修正了表格的对齐和格式，使其在 Markdown 渲染时显示正确。
- **字段说明**：对响应参数中的嵌套字段使用了更清晰的表示方式，便于理解。
- **一致性**：统一了字段描述、命名和表格格式，保持全篇文档风格一致。
- **示例数据**：在示例的 JSON 响应中，提供了更贴近实际的示例数据，帮助用户更直观地理解接口返回内容。

希望以上优化能够帮助您更好地使用和理解该操作指南。如有任何疑问，欢迎随时提问！
Loading

0 comments on commit 55d704d

Please sign in to comment.