# FileService

**Repository Path**: sky0535/FileService

## Basic Information

- **Project Name**: FileService
- **Description**: 基于 Spring Boot 3 的文件上传服务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot3

## README

# FileService

基于 Spring Boot 3 的文件上传服务，支持单文件和批量文件上传，内置 Web 上传页面。

## 功能特性

- ✅ **单文件上传** — 自定义文件名 + 描述元信息
- ✅ **批量文件上传** — 一次请求上传多个文件，支持可选 `folder` 子目录和 `tags` 标签
- ✅ **参数校验** — Jakarta Validation + BindingResult 双重校验
- ✅ **全局异常处理** — `@RestControllerAdvice` 统一捕获并返回标准错误
- ✅ **统一响应封装** — `Result<T>` 泛型返回结构
- ✅ **按日期存储** — 文件自动归档到 `uploads/yyyy-MM-dd/` 目录
- ✅ **Web 上传页面** — Bootstrap 5 + FontAwesome，支持拖拽上传、进度条
- ✅ **日志滚动** — Logback 控制台 + 文件滚动，业务日志独立输出

## 技术栈

| 分类 | 技术 |
|------|------|
| 框架 | Spring Boot 3.5.16 |
| 语言 | Java 21 |
| 构建 | Maven |
| 参数校验 | spring-boot-starter-validation (Jakarta) |
| 简化 | Lombok |
| 前端 UI | Bootstrap 5 + FontAwesome 6 |
| 前端请求 | Axios |
| 日志 | Logback (Spring 默认) |

## 项目结构

```
FileService/
├── pom.xml
├── README.md
└── src/main/
    ├── java/com/examples/
    │   ├── FileServiceApplication.java      # 启动类
    │   ├── controller/
    │   │   └── FileController.java          # REST API 控制器
    │   ├── service/
    │   │   └── FileService.java             # 文件保存核心逻辑
    │   ├── dto/
    │   │   ├── FileUpload.java              # 单文件上传请求 DTO
    │   │   ├── FilesUpload.java             # 批量文件上传请求 DTO
    │   │   └── UploadResult.java            # 上传结果 DTO
    │   ├── vo/
    │   │   └── Result.java                  # 统一响应封装
    │   └── handler/
    │       └── GlobalExceptionHandler.java  # 全局异常处理器
    └── resources/
        ├── application.yml                  # 应用配置
        ├── logback-spring.xml               # 日志配置
        └── static/                         # 前端静态资源
            ├── index.html                   # 上传页面
            ├── js/index.js                  # 前端上传逻辑（Axios + ESM）
            ├── js/axios/axios.min.js
            ├── css/main.css                 # 自定义样式
            ├── css/bootstrap/               # Bootstrap 5
            └── css/fontawesome/            # FontAwesome 6
```

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.8+

### 运行

```bash
# 克隆项目后
cd FileService
mvn spring-boot:run
```

### 测试

```bash
mvn test
```

启动成功后访问：<http://localhost:8080>

### 打包

```bash
mvn clean package
java -jar target/FileService-1.0-SNAPSHOT.jar
```

## API 接口

### 统一响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": { ... },
  "timestamp": 1727000000000
}
```

### 1. 单文件上传

`POST /api/file/upload`

**Content-Type**: `multipart/form-data`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | MultipartFile | ✅ | 上传的文件 |
| `name` | String | ✅ | 自定义文件名（不含扩展名） |
| `description` | String | ❌ | 文件描述 |

**示例响应**：

```json
{
  "code": 200,
  "message": "文件上传成功",
  "data": {
    "originalFilename": "photo.jpg",
    "newFilename": "my-photo.jpg",
    "relativePath": "2026-09-01/my-photo.jpg",
    "size": 1048576,
    "contentType": "image/jpeg"
  }
}
```

### 2. 批量文件上传

`POST /api/file/upload-batch`

**Content-Type**: `multipart/form-data`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `files` | MultipartFile[] | ✅ | 文件数组 |
| `folder` | String | ❌ | 目标子目录（存储路径追加此目录） |
| `tags` | String | ❌ | 标签，逗号分隔 |

**示例响应**：

```json
{
  "code": 200,
  "message": "批量上传成功",
  "data": [
    {
      "originalFilename": "a.png",
      "newFilename": "a.png",
      "relativePath": "2026-09-01/images/a.png",
      "size": 204800,
      "contentType": "image/png"
    },
    {
      "originalFilename": "b.pdf",
      "newFilename": "b.pdf",
      "relativePath": "2026-09-01/images/b.pdf",
      "size": 1024000,
      "contentType": "application/pdf"
    }
  ]
}
```

## 配置说明

### application.yml

```yaml
server:
  port: 8080

spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 100MB        # 单个文件最大 100MB
      max-request-size: 1000MB    # 单次请求最大 1GB
      file-size-threshold: 10KB   # 超过 10KB 写入临时文件

file:
  upload:
    path: uploads                 # 文件存储根目录（相对项目根）
```

### 文件存储策略

```
项目根/
├── uploads/
│   ├── 2026-09-01/              # 单文件上传
│   │   └── my-photo.jpg
│   └── 2026-09-01/images/       # 批量上传 + folder=images
│       ├── a.png
│       └── b.pdf
├── logs/
│   ├── app.log                  # 应用日志
│   ├── business.log             # 业务日志
│   └── app-2026-09-01.0.log     # 滚动归档
```

## 异常处理

| 异常类型 | HTTP Code | 触发场景 |
|----------|-----------|----------|
| `IllegalArgumentException` | 400 | Service 层主动校验失败 |
| `MethodArgumentNotValidException` | 400 | `@Valid @RequestBody` 校验失败 |
| `BindException` | 400 | 表单参数绑定校验失败 |
| `ConstraintViolationException` | 400 | `@RequestParam` / `@PathVariable` 校验失败 |
| `RuntimeException` | 500 | 文件 I/O / 目录创建等运行时错误 |
| `Exception` | 500 | 兜底处理 |

## 日志

日志配置位于 `logback-spring.xml`：

| Appender | 说明 |
|----------|------|
| CONSOLE | 控制台输出 |
| FILE | 全量应用日志（INFO+） |
| APP_LOG | `com.examples` 包业务日志（DEBUG+） |

**滚动策略**：
- 单文件最大 10MB
- 保留 30 天
- 总大小上限 300MB

## 核心类说明

| 类 | 职责 |
|----|------|
| `FileController` | REST 接口，接收上传请求并完成 DTO 校验 |
| `FileService` | 文件保存核心逻辑，按日期分目录存储 |
| `FileUpload` / `FilesUpload` | 单文件 / 批量上传请求参数 DTO |
| `UploadResult` | 上传成功后的文件信息封装 |
| `Result<T>` | 统一响应结构（code / message / data / timestamp） |
| `GlobalExceptionHandler` | 全局异常捕获，映射为标准 `Result` 响应 |