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

2.6 KiB

Raw Blame History

本地资源通用下载

接口信息

接口名称: 本地资源通用下载
接口路径: /file/resource
请求方法: GET
模块归属: file
版本号: v1.0.0
创建日期: 2026-01-18
最后更新: 2026-01-18

功能描述

提供本地资源的通用下载接口，用于下载服务器本地文件系统中的资源文件。支持文件路径安全验证，防止非法文件访问。该接口支持匿名访问。

请求参数

查询参数

参数名	类型	必填	描述	示例	默认值
filePath	String	是	本地文件路径	/static/images/logo.png	-

响应数据

成功响应

HTTP 状态码: 200 OK

Content-Type: application/octet-stream

Content-Disposition: attachment; filename="logo.png"

直接返回文件流，浏览器会自动触发下载。

失败响应

HTTP 状态码: 200 OK

Content-Type: text/html;charset=UTF-8

返回错误信息文本：

下载文件失败: 资源文件(../../../etc/passwd)非法，不允许下载。

接口示例

请求示例

curl -X GET "http://localhost:8080/file/resource?filePath=/static/images/logo.png" \
  -o logo.png

在浏览器中直接访问:

http://localhost:8080/file/resource?filePath=/static/images/logo.png

响应示例

成功: 返回文件流，浏览器自动下载文件

失败: 返回错误信息文本

错误处理

文件路径非法时返回错误信息（包含路径遍历攻击的文件）
文件不存在时返回错误信息
无权限访问文件时返回错误信息
IO 异常时返回错误信息

注意事项

该接口支持匿名访问，不需要认证
会进行文件路径安全验证，防止路径遍历攻击
只允许下载合法的资源文件
使用 FileUtils.checkAllowDownload() 验证文件路径
使用 FileUtils.setAttachmentResponseHeader() 设置下载响应头
错误时返回 HTML 格式的错误信息

实现细节

使用 @Anonymous 注解支持匿名访问
使用 FileUtils.checkAllowDownload() 验证文件路径合法性
使用 FileUtils.setAttachmentResponseHeader() 设置 Content-Disposition 响应头
使用 FileOperateUtils.downLoad() 下载本地文件
错误时重置响应并返回 HTML 格式的错误信息
使用 try-finally 确保输出流被正确关闭

2.6 KiB Raw Blame History