114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
|
# 统一预览接口
|
|||
|
|
|
|||
|
|
## 接口信息
|
|||
|
|
|
|||
|
|
- **接口名称**: 统一预览接口
|
|||
|
|
- **接口路径**: /file/preview 或 /file/{storageType}/{bucketName}/preview
|
|||
|
|
- **请求方法**: GET
|
|||
|
|
- **模块归属**: file
|
|||
|
|
- **版本号**: v1.0.0
|
|||
|
|
- **创建日期**: 2026-01-18
|
|||
|
|
- **最后更新**: 2026-01-18
|
|||
|
|
|
|||
|
|
## 功能描述
|
|||
|
|
|
|||
|
|
提供统一的文件预览接口，支持指定存储类型和存储桶，也可以使用默认存储。预览成功后直接返回文件流，浏览器会根据文件类型进行在线预览。该接口支持匿名访问。
|
|||
|
|
|
|||
|
|
## 请求参数
|
|||
|
|
|
|||
|
|
### 路径参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|||
|
|
|--------|------|------|------|------|
|
|||
|
|
| storageType | String | 否 | 存储类型，不传则使用默认存储 | minio, local, aliyun-oss |
|
|||
|
|
| bucketName | String | 否 | 存储桶名称，不传则使用默认存储桶 | primary, backup |
|
|||
|
|
|
|||
|
|
### 查询参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 | 默认值 |
|
|||
|
|
|--------|------|------|------|------|--------|
|
|||
|
|
| filePath | String | 是 | 文件路径，需要 URL 编码 | upload%2F1234567890_test.jpg | - |
|
|||
|
|
|
|||
|
|
## 响应数据
|
|||
|
|
|
|||
|
|
### 成功响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 200 OK
|
|||
|
|
|
|||
|
|
**Content-Type**: 根据文件类型自动识别（如 image/jpeg, application/pdf 等）
|
|||
|
|
|
|||
|
|
直接返回文件流，浏览器会根据 Content-Type 进行在线预览。
|
|||
|
|
|
|||
|
|
### 失败响应
|
|||
|
|
|
|||
|
|
**HTTP 状态码**: 200 OK
|
|||
|
|
|
|||
|
|
**Content-Type**: text/plain;charset=UTF-8
|
|||
|
|
|
|||
|
|
返回错误信息文本：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
预览失败: 文件不存在
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 接口示例
|
|||
|
|
|
|||
|
|
### 请求示例
|
|||
|
|
|
|||
|
|
**使用默认存储**:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X GET "http://localhost:8080/file/preview?filePath=upload%2F1234567890_test.jpg" \
|
|||
|
|
-o preview.jpg
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**指定存储类型和存储桶**:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X GET "http://localhost:8080/file/minio/primary/preview?filePath=upload%2F1234567890_test.jpg" \
|
|||
|
|
-o preview.jpg
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**在浏览器中直接访问**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
http://localhost:8080/file/preview?filePath=upload/1234567890_test.jpg
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 响应示例
|
|||
|
|
|
|||
|
|
**成功**: 返回文件流，浏览器根据文件类型进行预览
|
|||
|
|
|
|||
|
|
**失败**: 返回错误信息文本
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
- 文件不存在时返回错误信息
|
|||
|
|
- 存储类型或存储桶不存在时返回错误
|
|||
|
|
- 文件路径为空时返回错误
|
|||
|
|
- 文件路径编码错误时返回错误
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- 该接口支持匿名访问，不需要认证
|
|||
|
|
- 文件路径需要进行 URL 编码
|
|||
|
|
- 浏览器会根据文件类型自动进行预览
|
|||
|
|
- 支持的预览类型：图片（jpg、png、gif等）、PDF、文本文件等
|
|||
|
|
- 不指定存储类型时使用系统配置的默认存储
|
|||
|
|
- 使用 `URLConnection.guessContentTypeFromName()` 自动识别文件类型
|
|||
|
|
|
|||
|
|
## 相关接口
|
|||
|
|
|
|||
|
|
- [统一上传接口](./0002-upload.md) - 上传文件
|
|||
|
|
- [统一下载接口](./0003-download.md) - 下载文件
|
|||
|
|
- [本地资源通用下载](./0005-resource.md) - 下载本地资源文件
|
|||
|
|
|
|||
|
|
## 实现细节
|
|||
|
|
|
|||
|
|
- 使用 `@Anonymous` 注解支持匿名访问
|
|||
|
|
- 使用 `StorageService.downLoad()` 方法获取文件流
|
|||
|
|
- 使用 `URLConnection.guessContentTypeFromName()` 自动识别文件类型
|
|||
|
|
- 使用 `IOUtils.copy()` 将文件流复制到响应输出流
|
|||
|
|
- 使用 `URLDecoder.decode()` 解码文件路径
|
|||
|
|
- 如果无法识别文件类型，默认使用 application/octet-stream
|