一、技术选型与开发环境准备

1.1 核心组件说明

Spring Boot 3作为后端框架提供RESTful API支持，Element Plus作为Vue 3的组件库构建前端交互界面，Hutool工具包简化文件操作。这种组合兼顾开发效率与系统稳定性，特别适合中小型项目的快速迭代。

1.2 依赖配置指南

在pom.xml中需配置三个关键依赖：

<!-- Spring Web模块 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Hutool工具包（建议使用最新稳定版） -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.25</version>
</dependency>
<!-- 文件上传支持（需显式声明） -->
<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.5</version>
</dependency>

二、文件存储系统设计

2.1 存储路径规划

采用三级目录结构：

/project_root
    ├── /files          # 基础存储目录
    │   ├── /images     # 图片专用目录
    │   ├── /documents  # 文档专用目录
    │   └── /temp       # 临时文件目录

通过System.getProperty("user.dir")获取项目根路径，结合FileUtil.mkdir()自动创建目录结构。建议添加目录存在性检查：

private static final String BASE_PATH = System.getProperty("user.dir") + "/files/";
public static void ensureDirectory(String subDir) {
    String fullPath = BASE_PATH + subDir;
    if (!FileUtil.isDirectory(fullPath)) {
        FileUtil.mkdir(fullPath);
    }
}

2.2 文件命名策略

采用”时间戳+原始文件名+随机数”的三段式命名：

public static String generateUniqueFilename(String originalName) {
    long timestamp = System.currentTimeMillis();
    String ext = FileUtil.extName(originalName);
    String prefix = FileUtil.mainName(originalName);
    String randomSuffix = RandomUtil.randomString(4);
    return String.format("%d_%s_%s.%s", 
        timestamp, prefix, randomSuffix, ext);
}

三、核心功能实现

3.1 文件上传接口

完整控制器实现示例：

@RestController
@RequestMapping("/api/files")
public class FileController {
    @PostMapping("/upload")
    public ResponseEntity<Map<String, String>> uploadFile(
            @RequestParam("file") MultipartFile file,
            @RequestParam(value = "type", required = false) String type) {
        Map<String, String> result = new HashMap<>();
        try {
            // 1. 参数校验
            if (file.isEmpty()) {
                throw new IllegalArgumentException("文件不能为空");
            }
            // 2. 确定存储子目录
            String subDir = "default";
            if ("image".equals(type)) {
                subDir = "images";
            } else if ("doc".equals(type)) {
                subDir = "documents";
            }
            ensureDirectory(subDir);
            // 3. 生成唯一文件名
            String uniqueName = generateUniqueFilename(file.getOriginalFilename());
            String fullPath = BASE_PATH + subDir + "/" + uniqueName;
            // 4. 文件写入
            FileUtil.writeBytes(file.getBytes(), fullPath);
            // 5. 返回访问URL（需配置静态资源映射）
            String accessUrl = "/downloads/" + subDir + "/" + uniqueName;
            result.put("url", accessUrl);
            result.put("filename", file.getOriginalFilename());
            return ResponseEntity.ok(result);
        } catch (IOException e) {
            throw new RuntimeException("文件上传失败", e);
        }
    }
}

3.2 文件下载功能

需在Spring Boot配置类中添加静态资源映射：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/downloads/**")
                .addResourceLocations("file:" + BASE_PATH);
    }
}

下载接口实现：

@GetMapping("/download/{path:.+}")
public ResponseEntity<Resource> downloadFile(
        @PathVariable String path) throws IOException {
    String fullPath = BASE_PATH + path;
    File file = new File(fullPath);
    if (!file.exists()) {
        return ResponseEntity.notFound().build();
    }
    Path filePath = Paths.get(fullPath);
    Resource resource = new UrlResource(filePath.toUri());
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, 
                   "attachment; filename=\"" + file.getName() + "\"")
            .body(resource);
}

四、前端集成方案

4.1 Element Plus上传组件

Vue组件示例：

<template>
  <el-upload
    class="upload-demo"
    action="/api/files/upload"
    :on-success="handleSuccess"
    :before-upload="beforeUpload"
    :data="{type: 'image'}"
    multiple
    :limit="3"
    :on-exceed="handleExceed">
    <el-button type="primary">点击上传</el-button>
    <template #tip>
      <div class="el-upload__tip">
        支持jpg/png文件，且不超过500kb
      </div>
    </template>
  </el-upload>
</template>
<script setup>
const beforeUpload = (file) => {
  const isImage = ['image/jpeg', 'image/png'].includes(file.type);
  const isLt500K = file.size / 1024 < 500;
  if (!isImage) {
    ElMessage.error('只能上传JPG/PNG格式!');
  }
  if (!isLt500K) {
    ElMessage.error('文件大小不能超过500KB!');
  }
  return isImage && isLt500K;
};
const handleSuccess = (response) => {
  ElMessage.success('上传成功');
  console.log('访问地址:', response.url);
};
const handleExceed = () => {
  ElMessage.warning('最多只能上传3个文件');
};
</script>

五、安全与性能优化

5.1 安全防护措施

文件类型校验：通过file.getContentType()验证MIME类型

文件大小限制：在Spring Boot配置中添加

spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB

访问权限控制：结合Spring Security实现鉴权

5.2 性能优化策略

大文件分片上传：使用WebUploader等组件实现
异步处理：通过@Async注解实现后台处理
缓存机制：对频繁访问的文件启用CDN缓存

六、异常处理机制

自定义异常类示例：

public class FileOperationException extends RuntimeException {
    private int errorCode;
    public FileOperationException(int code, String message) {
        super(message);
        this.errorCode = code;
    }
    // Getter方法
}
@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(FileOperationException.class)
    public ResponseEntity<Map<String, Object>> handleFileException(FileOperationException ex) {
        Map<String, Object> body = new HashMap<>();
        body.put("code", ex.getErrorCode());
        body.put("message", ex.getMessage());
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(body);
    }
}

七、部署注意事项

存储目录权限：确保应用有读写权限
磁盘空间监控：建议设置告警阈值
日志记录：完整记录上传下载操作
备份策略：定期备份重要文件

通过以上技术方案，开发者可以快速构建出稳定可靠的文件管理系统。实际开发中，可根据具体业务需求调整存储策略、安全规则和性能参数，打造符合企业标准的文件处理解决方案。

Spring Boot 3与Element Plus集成：实现高效文件上传下载功能