100 lines
2.6 KiB
Markdown
100 lines
2.6 KiB
Markdown
# 本地资源通用下载
|
|
|
|
## 接口信息
|
|
|
|
- **接口名称**: 本地资源通用下载
|
|
- **接口路径**: /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)非法，不允许下载。
|
|
```
|
|
|
|
## 接口示例
|
|
|
|
### 请求示例
|
|
|
|
```bash
|
|
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 格式的错误信息
|
|
|
|
## 相关接口
|
|
|
|
- [统一上传接口](./0002-upload.md) - 上传文件
|
|
- [统一下载接口](./0003-download.md) - 下载存储中的文件
|
|
- [统一预览接口](./0004-preview.md) - 在线预览文件
|
|
|
|
## 实现细节
|
|
|
|
- 使用 `@Anonymous` 注解支持匿名访问
|
|
- 使用 `FileUtils.checkAllowDownload()` 验证文件路径合法性
|
|
- 使用 `FileUtils.setAttachmentResponseHeader()` 设置 Content-Disposition 响应头
|
|
- 使用 `FileOperateUtils.downLoad()` 下载本地文件
|
|
- 错误时重置响应并返回 HTML 格式的错误信息
|
|
- 使用 try-finally 确保输出流被正确关闭
|