# 统一下载接口

## 接口信息

- **接口名称**: 统一下载接口
- **接口路径**: /file/download 或 /file/{storageType}/{bucketName}/download
- **请求方法**: GET
- **模块归属**: file
- **版本号**: v1.0.0
- **创建日期**: 2026-01-18
- **最后更新**: 2026-01-18

## 功能描述

提供统一的文件下载接口，支持指定存储类型和存储桶，也可以使用默认存储。下载成功后直接返回文件流。

## 请求参数

### 路径参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| storageType | String | 否 | 存储类型，不传则使用默认存储 | minio, local, aliyun-oss |
| bucketName | String | 否 | 存储桶名称，不传则使用默认存储桶 | primary, backup |

### 查询参数

| 参数名 | 类型 | 必填 | 描述 | 示例 | 默认值 |
|--------|------|------|------|------|--------|
| filePath | String | 是 | 文件路径 | upload/1234567890_test.jpg | - |

## 响应数据

### 成功响应

**HTTP 状态码**: 200 OK

**Content-Type**: application/octet-stream

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

### 失败响应

**HTTP 状态码**: 200 OK

**Content-Type**: text/plain;charset=UTF-8

返回错误信息文本：

```
下载失败: 文件不存在
```

## 接口示例

### 请求示例

**使用默认存储**:

```bash
curl -X GET "http://localhost:8080/file/download?filePath=upload/1234567890_test.jpg" \
  -H "Authorization: Bearer [token]" \
  -o downloaded_file.jpg
```

**指定存储类型和存储桶**:

```bash
curl -X GET "http://localhost:8080/file/minio/primary/download?filePath=upload/1234567890_test.jpg" \
  -H "Authorization: Bearer [token]" \
  -o downloaded_file.jpg
```

### 响应示例

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

**失败**: 返回错误信息文本

## 错误处理

- 文件不存在时返回错误信息
- 存储类型或存储桶不存在时返回错误
- 文件路径为空时返回错误
- 无权限访问文件时返回错误

## 注意事项

- 该接口直接返回文件流，不是 JSON 格式
- 浏览器会自动触发文件下载
- 错误时返回纯文本错误信息
- 支持多种存储类型：local、minio、aliyun-oss 等
- 不指定存储类型时使用系统配置的默认存储

## 相关接口

- [统一上传接口](./0002-upload.md) - 上传文件
- [统一预览接口](./0004-preview.md) - 在线预览文件
- [本地资源通用下载](./0005-resource.md) - 下载本地资源文件

## 实现细节

- 使用 `StorageService.downLoad()` 方法下载文件
- 设置响应 Content-Type 为 application/octet-stream
- 错误时设置 Content-Type 为 text/plain;charset=UTF-8
- 支持大文件下载，使用流式传输避免内存溢出