kris/datai

Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建

- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。

2026-01-19 10:06:09 +08:00

3.1 KiB

Raw Blame History

统一预览接口

接口信息

接口名称: 统一预览接口
接口路径: /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

3.1 KiB Raw Blame History Unescape Escape