文件上传下载与静态资源

@RestController
@RequestMapping("/api/files")
public class FileController {

    private final FileStorage storage;

    FileController(FileStorage storage) { this.storage = storage; }

    // 单文件：字段名与前端 FormData 的 key 对应
    @PostMapping("/avatar")
    public Map<String, String> uploadAvatar(@RequestParam("file") MultipartFile file) throws IOException {
        String url = storage.save(file);
        return Map.of("url", url);
    }

    // 多文件：同名字段重复出现，或前端 append 多次同名 key
    @PostMapping("/gallery")
    public List<Map<String, String>> uploadGallery(@RequestParam("files") List<MultipartFile> files) {
        return files.stream()
                .map(f -> {
                    try {
                        return Map.of("url", storage.save(f));
                    } catch (IOException e) {
                        throw new IllegalStateException("保存失败", e);
                    }
                })
                .toList();
    }
}

spring:
  servlet:
    multipart:
      max-file-size: 5MB       # 单个文件上限
      max-request-size: 20MB   # 整个请求（多文件之和）上限

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ResponseEntity<Map<String, String>> handleTooLarge(MaxUploadSizeExceededException e) {
        return ResponseEntity.badRequest()
                .body(Map.of("code", "FILE_TOO_LARGE", "message", "文件超过 5MB 限制"));
    }
}

// 第一道：扩展名白名单（防新手误传，挡不住改名）
private static final Set<String> ALLOWED = Set.of("jpg", "jpeg", "png", "webp");

// 第二道：魔数校验（文件的头部字节不会说谎）
private boolean isRealImage(MultipartFile file) throws IOException {
    byte[] head = new byte[8];
    try (InputStream in = file.getInputStream()) {
        if (in.read(head) != 8) return false;
    }
    return head[0] == (byte) 0x89 && head[1] == 'P'    // PNG: 89 50 4E 47
        || (head[0] == 'F' && head[1] == 'F' && head[2] == 'D' && head[3] == '8'); // JPEG: FF D8
}

@Service
public class FileStorage {

    private final Path root;

    public FileStorage(@Value("${app.upload.dir:/var/fandex/uploads}") String dir) throws IOException {
        this.root = Path.of(dir).toAbsolutePath().normalize();
        Files.createDirectories(root);
    }

    public String save(MultipartFile file) throws IOException {
        String original = file.getOriginalFilename();
        String ext = StringUtils.getFilenameExtension(original);
        String safeName = UUID.randomUUID() + (ext != null ? "." + ext.toLowerCase() : "");

        Path target = root.resolve(safeName).normalize();
        if (!target.startsWith(root)) {          // 路径穿越防线
            throw new SecurityException("非法路径");
        }
        file.transferTo(target);
        return "/uploads/" + safeName;
    }
}

@GetMapping("/reports/{month}")
public ResponseEntity<Resource> downloadReport(@PathVariable String month) throws IOException {
    Path file = Path.of("/var/fandex/reports", "sales-" + month + ".xlsx").normalize();
    if (!file.startsWith("/var/fandex/reports")) {   // 下载路径同样要防穿越
        return ResponseEntity.notFound().build();
    }

    String downloadName = URLEncoder.encode("销售报表-" + month + ".xlsx", StandardCharsets.UTF_8);

    return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"))
            .header(HttpHeaders.CONTENT_DISPOSITION,
                    "attachment; filename*=UTF-8''" + downloadName)
            .body(new FileSystemResource(file));
}

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/uploads/**")                       // URL 前缀
                .addResourceLocations("file:/var/fandex/uploads/");      // 磁盘目录
    }
}

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/")
            .resourceChain(true)
            .addResolver(new PathResourceResolver() {
                @Override
                protected Resource getResource(String resourcePath, Resource location) throws IOException {
                    Resource requested = location.createRelative(resourcePath);
                    // SPA 路由兜底：文件不存在时回退到 index.html，交给前端路由
                    return requested.exists() && requested.isReadable()
                            ? requested
                            : location.createRelative("index.html");
                }
            });
}