本文详细介绍使用 spring boot 快速构建安全、可扩展的文件上传 rest 接口，涵盖控制器定义、请求模型设计、服务层处理及关键配置要点。
本文详细介绍使用 spring boot 快速构建安全、可扩展的文件上传 rest 接口，涵盖控制器定义、请求模型设计、服务层处理及关键配置要点。
在 Spring Boot 微服务架构中，实现文件上传需兼顾 HTTP 协议规范、Spring MVC 机制与实际业务逻辑。核心在于正确处理 multipart/form-data 请求，并确保服务层能可靠解析、校验和持久化上传文件。
✅ 基础控制器实现
使用 @PostMapping 并显式声明 consumes = MediaType.MULTIPART_FORM_DATA_VALUE，明确告知 Spring 此接口仅接受表单文件上传请求：
@PostMapping(path = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<UserImageModel> uploadDocument(
@ModelAttribute UserImageRequestModel request) {
UserImageModel result = userProfileService.saveDocument(request);
return ResponseEntity.ok(result);
}⚠️ 注意：必须使用 @ModelAttribute（而非 @RequestBody）绑定 MultipartFile，因为 multipart 数据无法通过 JSON 解析器反序列化。
? 请求数据模型设计
定义简洁、语义清晰的 DTO，封装文件及关联元数据：
@Getter
@Setter
public class UserImageRequestModel {
private MultipartFile file; // 必须为 MultipartFile 类型
private Long userId; // 业务上下文标识（如用户ID）
private String description; // 可选：附加说明字段
}Spring 会自动将 HTML 表单中的 <input type="file" name="file"> 和 <input name="userId"> 映射到对应字段。
⚙️ 服务层处理建议
在 UserProfileService 中完成校验、存储与响应构造：
public UserImageModel saveDocument(UserImageRequestModel request) {
// 1. 校验非空与大小限制（推荐结合 @Valid + 自定义约束）
if (request.getFile() == null || request.getFile().isEmpty()) {
throw new IllegalArgumentException("文件不能为空");
}
if (request.getFile().getSize() > 5 * 1024 * 1024) { // 5MB 限制
throw new IllegalArgumentException("文件大小不能超过 5MB");
}
// 2. 保存文件（示例：本地存储，生产环境建议用 MinIO/OSS）
String fileName = UUID.randomUUID() + "_" + request.getFile().getOriginalFilename();
Path uploadDir = Paths.get("uploads/");
try {
Files.createDirectories(uploadDir);
Path targetPath = uploadDir.resolve(fileName);
request.getFile().transferTo(targetPath);
// 3. 保存元数据到数据库（如 MySQL）
DocumentEntity entity = new DocumentEntity();
entity.setUserId(request.getUserId());
entity.setFileName(fileName);
entity.setFilePath(targetPath.toString());
documentRepository.save(entity);
return UserImageModel.builder()
.id(entity.getId())
.fileName(fileName)
.size(request.getFile().getSize())
.uploadTime(LocalDateTime.now())
.build();
} catch (IOException e) {
throw new RuntimeException("文件保存失败", e);
}
}?️ 关键配置项（application.yml）
确保 Spring Boot 允许足够大的上传文件并启用 multipart 支持（Spring Boot 2.0+ 默认启用）：
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 10MB
# 启用后支持流式上传（大文件场景推荐）
enabled: true? 安全与生产建议
- 使用 @Valid + 自定义 @ValidFile 注解进行前置校验（如类型白名单：image/*, application/pdf）；
- 避免直接暴露文件系统路径，返回统一访问 URL（如 /api/files/{id}），由 Controller 提供下载接口；
- 生产环境务必禁用 static 目录直接访问上传目录，改用 ResourceHttpRequestHandler 或专用文件服务；
- 考虑引入异步处理（@Async）避免阻塞主线程，尤其面对高并发小文件上传场景。
通过以上结构化实现，你将获得一个健壮、可维护且符合 Spring 最佳实践的文件上传 REST 端点。
