mirror of
https://github.com/vastsa/FileCodeBox.git
synced 2026-11-20 13:29:56 +08:00
454 lines
11 KiB
Markdown
454 lines
11 KiB
Markdown
# 预签名上传 API 文档
|
||||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
预签名上传功能提供统一的文件上传接口,根据后端存储类型自动选择最优上传方式:
|
|||
|
|
|
|||
|
|
- **S3 存储**: 返回预签名 URL,客户端直传 S3(减少服务器带宽压力)
|
|||
|
|
- **其他存储**: 返回代理上传 URL,通过服务器中转上传
|
|||
|
|
|
|||
|
|
## 上传流程
|
|||
|
|
|
|||
|
|
### 流程图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────┐ 1. 初始化上传 ┌─────────┐
|
|||
|
|
│ 客户端 │ ──────────────────────▶ │ 服务器 │
|
|||
|
|
└─────────┘ └─────────┘
|
|||
|
|
│ │
|
|||
|
|
│◀─────── 返回 upload_url + mode ──┤
|
|||
|
|
│ │
|
|||
|
|
│ ┌─────────────────────────────────────────┐
|
|||
|
|
│ │ if mode == "direct" (S3存储) │
|
|||
|
|
│ │ 2a. PUT 文件到 upload_url (S3) │
|
|||
|
|
│ │ 3a. POST /confirm 确认上传 │
|
|||
|
|
│ │ │
|
|||
|
|
│ │ if mode == "proxy" (其他存储) │
|
|||
|
|
│ │ 2b. PUT 文件到 upload_url (服务器) │
|
|||
|
|
│ │ (自动返回分享码,无需确认) │
|
|||
|
|
│ └─────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
获取分享码
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## API 端点
|
|||
|
|
|
|||
|
|
### 1. 初始化上传
|
|||
|
|
|
|||
|
|
初始化预签名上传会话,获取上传 URL 和模式。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /presign/upload/init
|
|||
|
|
Content-Type: application/json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**请求体**
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
|||
|
|
| ------------ | ------- | ---- | ------ | --------------------------------------- |
|
|||
|
|
| file_name | string | ✅ | - | 文件名(含扩展名) |
|
|||
|
|
| file_size | integer | ✅ | - | 文件大小(字节) |
|
|||
|
|
| expire_value | integer | ❌ | 1 | 过期时间值 |
|
|||
|
|
| expire_style | string | ❌ | "day" | 过期类型:day/hour/minute/forever/count |
|
|||
|
|
|
|||
|
|
**请求示例**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"file_name": "document.pdf",
|
|||
|
|
"file_size": 1048576,
|
|||
|
|
"expire_value": 7,
|
|||
|
|
"expire_style": "day"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": {
|
|||
|
|
"upload_id": "a1b2c3d4e5f6...",
|
|||
|
|
"upload_url": "https://bucket.s3.amazonaws.com/path?X-Amz-Signature=...",
|
|||
|
|
"mode": "direct",
|
|||
|
|
"save_path": "share/data/2024/01/01/uuid/document.pdf",
|
|||
|
|
"expires_in": 900
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应字段说明**
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 说明 |
|
|||
|
|
| ---------- | ------- | ----------------------------------------------------- |
|
|||
|
|
| upload_id | string | 上传会话 ID,后续操作需要 |
|
|||
|
|
| upload_url | string | 上传目标 URL |
|
|||
|
|
| mode | string | 上传模式:`direct`(直传 S3)或 `proxy`(服务器代理) |
|
|||
|
|
| save_path | string | 文件存储路径 |
|
|||
|
|
| expires_in | integer | URL 有效期(秒),默认 900 秒(15 分钟) |
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 |
|
|||
|
|
| ------ | ------------------------------ |
|
|||
|
|
| 400 | 过期时间类型错误 |
|
|||
|
|
| 403 | 文件大小超过限制 / IP 频率限制 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2a. 直传模式 - 上传文件到 S3
|
|||
|
|
|
|||
|
|
当 `mode == "direct"` 时,客户端直接将文件 PUT 到返回的预签名 URL。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
PUT {upload_url}
|
|||
|
|
Content-Type: application/octet-stream
|
|||
|
|
|
|||
|
|
[文件二进制内容]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意事项**
|
|||
|
|
|
|||
|
|
- 直接使用返回的 `upload_url`,不要修改
|
|||
|
|
- Content-Type 建议使用 `application/octet-stream`
|
|||
|
|
- 这是直接请求 S3,不经过服务器
|
|||
|
|
|
|||
|
|
**JavaScript 示例**
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
const response = await fetch(uploadUrl, {
|
|||
|
|
method: 'PUT',
|
|||
|
|
body: file,
|
|||
|
|
headers: {
|
|||
|
|
'Content-Type': 'application/octet-stream',
|
|||
|
|
},
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
if (response.ok) {
|
|||
|
|
// 上传成功,调用确认接口
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2b. 代理模式 - 上传文件到服务器
|
|||
|
|
|
|||
|
|
当 `mode == "proxy"` 时,客户端将文件 PUT 到服务器代理端点。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
PUT /presign/upload/proxy/{upload_id}
|
|||
|
|
Content-Type: multipart/form-data
|
|||
|
|
|
|||
|
|
file: [文件]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**路径参数**
|
|||
|
|
|
|||
|
|
| 参数 | 说明 |
|
|||
|
|
| --------- | ------------------------- |
|
|||
|
|
| upload_id | 初始化时返回的上传会话 ID |
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": {
|
|||
|
|
"code": "123456",
|
|||
|
|
"name": "document.pdf"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意**: 代理模式上传成功后直接返回分享码,无需调用确认接口。
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 |
|
|||
|
|
| ------ | --------------------------------------- |
|
|||
|
|
| 400 | 文件大小与声明不符 / 会话不支持代理上传 |
|
|||
|
|
| 404 | 上传会话不存在或已过期 |
|
|||
|
|
| 500 | 文件保存失败 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. 确认上传(仅直传模式)
|
|||
|
|
|
|||
|
|
直传模式下,客户端完成 S3 上传后调用此接口确认并获取分享码。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /presign/upload/confirm/{upload_id}
|
|||
|
|
Content-Type: application/json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**路径参数**
|
|||
|
|
|
|||
|
|
| 参数 | 说明 |
|
|||
|
|
| --------- | ------------------------- |
|
|||
|
|
| upload_id | 初始化时返回的上传会话 ID |
|
|||
|
|
|
|||
|
|
**请求体**
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
|||
|
|
| ------------ | ------- | ---- | ------ | ---------- |
|
|||
|
|
| expire_value | integer | ❌ | 1 | 过期时间值 |
|
|||
|
|
| expire_style | string | ❌ | "day" | 过期类型 |
|
|||
|
|
|
|||
|
|
**请求示例**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"expire_value": 7,
|
|||
|
|
"expire_style": "day"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": {
|
|||
|
|
"code": "123456",
|
|||
|
|
"name": "document.pdf"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 |
|
|||
|
|
| ------ | --------------------------------------------- |
|
|||
|
|
| 400 | 会话不支持直传确认 |
|
|||
|
|
| 404 | 上传会话不存在或已过期 / 文件未上传或上传失败 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. 查询上传状态
|
|||
|
|
|
|||
|
|
查询上传会话的当前状态。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /presign/upload/status/{upload_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": {
|
|||
|
|
"upload_id": "a1b2c3d4e5f6...",
|
|||
|
|
"file_name": "document.pdf",
|
|||
|
|
"file_size": 1048576,
|
|||
|
|
"mode": "direct",
|
|||
|
|
"created_at": "2024-01-01T12:00:00",
|
|||
|
|
"expires_at": "2024-01-01T12:15:00",
|
|||
|
|
"is_expired": false
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 |
|
|||
|
|
| ------ | -------------- |
|
|||
|
|
| 404 | 上传会话不存在 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5. 取消上传
|
|||
|
|
|
|||
|
|
取消上传会话并清理相关资源。
|
|||
|
|
|
|||
|
|
**请求**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
DELETE /presign/upload/{upload_id}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": {
|
|||
|
|
"message": "上传会话已取消"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
| 状态码 | 说明 |
|
|||
|
|
| ------ | -------------- |
|
|||
|
|
| 404 | 上传会话不存在 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 前端集成示例
|
|||
|
|
|
|||
|
|
### 完整上传流程(JavaScript/TypeScript)
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface PresignInitResponse {
|
|||
|
|
upload_id: string
|
|||
|
|
upload_url: string
|
|||
|
|
mode: 'direct' | 'proxy'
|
|||
|
|
save_path: string
|
|||
|
|
expires_in: number
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
interface UploadResult {
|
|||
|
|
code: string
|
|||
|
|
name: string
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function uploadFile(
|
|||
|
|
file: File,
|
|||
|
|
expireValue: number = 1,
|
|||
|
|
expireStyle: string = 'day'
|
|||
|
|
): Promise<UploadResult> {
|
|||
|
|
// 1. 初始化上传
|
|||
|
|
const initResponse = await fetch('/presign/upload/init', {
|
|||
|
|
method: 'POST',
|
|||
|
|
headers: { 'Content-Type': 'application/json' },
|
|||
|
|
body: JSON.stringify({
|
|||
|
|
file_name: file.name,
|
|||
|
|
file_size: file.size,
|
|||
|
|
expire_value: expireValue,
|
|||
|
|
expire_style: expireStyle,
|
|||
|
|
}),
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const initData = await initResponse.json()
|
|||
|
|
if (initData.code !== 200) {
|
|||
|
|
throw new Error(initData.detail)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const { upload_id, upload_url, mode } = initData.detail as PresignInitResponse
|
|||
|
|
|
|||
|
|
// 2. 根据模式上传文件
|
|||
|
|
if (mode === 'direct') {
|
|||
|
|
// 直传模式:上传到S3
|
|||
|
|
const uploadResponse = await fetch(upload_url, {
|
|||
|
|
method: 'PUT',
|
|||
|
|
body: file,
|
|||
|
|
headers: { 'Content-Type': 'application/octet-stream' },
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
if (!uploadResponse.ok) {
|
|||
|
|
throw new Error('S3上传失败')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 3. 确认上传
|
|||
|
|
const confirmResponse = await fetch(
|
|||
|
|
`/presign/upload/confirm/${upload_id}`,
|
|||
|
|
{
|
|||
|
|
method: 'POST',
|
|||
|
|
headers: { 'Content-Type': 'application/json' },
|
|||
|
|
body: JSON.stringify({
|
|||
|
|
expire_value: expireValue,
|
|||
|
|
expire_style: expireStyle,
|
|||
|
|
}),
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
const confirmData = await confirmResponse.json()
|
|||
|
|
if (confirmData.code !== 200) {
|
|||
|
|
throw new Error(confirmData.detail)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return confirmData.detail
|
|||
|
|
} else {
|
|||
|
|
// 代理模式:上传到服务器
|
|||
|
|
const formData = new FormData()
|
|||
|
|
formData.append('file', file)
|
|||
|
|
|
|||
|
|
const uploadResponse = await fetch(upload_url, {
|
|||
|
|
method: 'PUT',
|
|||
|
|
body: formData,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const uploadData = await uploadResponse.json()
|
|||
|
|
if (uploadData.code !== 200) {
|
|||
|
|
throw new Error(uploadData.detail)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return uploadData.detail
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 使用示例
|
|||
|
|
const file = document.querySelector('input[type="file"]').files[0]
|
|||
|
|
const result = await uploadFile(file, 7, 'day')
|
|||
|
|
console.log('分享码:', result.code)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Vue 3 组件示例
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<div>
|
|||
|
|
<input type="file" @change="handleFileSelect" />
|
|||
|
|
<button @click="upload" :disabled="!selectedFile || uploading">
|
|||
|
|
{{ uploading ? '上传中...' : '上传' }}
|
|||
|
|
</button>
|
|||
|
|
<div v-if="shareCode">分享码: {{ shareCode }}</div>
|
|||
|
|
<div v-if="error" class="error">{{ error }}</div>
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<script setup lang="ts">
|
|||
|
|
import { ref } from 'vue'
|
|||
|
|
|
|||
|
|
const selectedFile = ref<File | null>(null)
|
|||
|
|
const uploading = ref(false)
|
|||
|
|
const shareCode = ref('')
|
|||
|
|
const error = ref('')
|
|||
|
|
|
|||
|
|
function handleFileSelect(e: Event) {
|
|||
|
|
const input = e.target as HTMLInputElement
|
|||
|
|
selectedFile.value = input.files?.[0] || null
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function upload() {
|
|||
|
|
if (!selectedFile.value) return
|
|||
|
|
|
|||
|
|
uploading.value = true
|
|||
|
|
error.value = ''
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
const result = await uploadFile(selectedFile.value)
|
|||
|
|
shareCode.value = result.code
|
|||
|
|
} catch (e) {
|
|||
|
|
error.value = e.message
|
|||
|
|
} finally {
|
|||
|
|
uploading.value = false
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **会话有效期**: 上传会话默认 15 分钟后过期,请在有效期内完成上传
|
|||
|
|
2. **文件大小限制**: 受系统配置 `uploadSize` 限制
|
|||
|
|
3. **过期类型**: 支持 `day`、`hour`、`minute`、`forever`、`count`
|
|||
|
|
4. **CORS**: 直传模式下,S3 需要配置正确的 CORS 策略
|
|||
|
|
5. **重试机制**: 建议实现上传失败重试逻辑
|