3.1 KiB
3.1 KiB
统一预览接口
接口信息
- 接口名称: 统一预览接口
- 接口路径: /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
返回错误信息文本：
预览失败: 文件不存在
接口示例
请求示例
使用默认存储:
curl -X GET "http://localhost:8080/file/preview?filePath=upload%2F1234567890_test.jpg" \
-o preview.jpg
指定存储类型和存储桶:
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()自动识别文件类型
相关接口
实现细节
- 使用
@Anonymous注解支持匿名访问 - 使用
StorageService.downLoad()方法获取文件流 - 使用
URLConnection.guessContentTypeFromName()自动识别文件类型 - 使用
IOUtils.copy()将文件流复制到响应输出流 - 使用
URLDecoder.decode()解码文件路径 - 如果无法识别文件类型，默认使用 application/octet-stream