# 本地资源通用下载

## 接口信息

- **接口名称**: 本地资源通用下载
- **接口路径**: /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 确保输出流被正确关闭