Spring Boot 控制层参数绑定 @RequestPart 注解详解

2.2 文件 + 普通参数（@RequestPart 的优势）

@RestController
@RequestMapping("/api/advanced")
public class AdvancedUploadController {
    // 文件 + 字符串参数
    @PostMapping(value = "/with-text", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithText(
            @RequestPart("file") MultipartFile file,
            @RequestPart("description") String description) {
        return String.format("File: %s, Description: %s",
                file.getOriginalFilename(), description);
    }

    // 文件 + JSON 对象
    @PostMapping(value = "/with-json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithJson(
            @RequestPart("file") MultipartFile file,
            @RequestPart("metadata") FileMetadata metadata) {
        return String.format("File: %s, Metadata: %s",
                file.getOriginalFilename(), metadata.toString());
    }

    // 多个不同类型的部分
    @PostMapping(value = "/complex", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public Map<String, Object> complexUpload(
            @RequestPart("profileImage") MultipartFile image,
            @RequestPart("profileData") UserProfile profile,
            @RequestPart("settings") String settingsJson,
            @RequestPart("documents") MultipartFile[] documents) {
        Map<String, Object> result = new HashMap<>();
        result.put("image", image.getOriginalFilename());
        result.put("profile", profile);
        result.put("settings", settingsJson);
        result.put("documentCount", documents.length);
        return result;
    }
}

// 元数据类
class FileMetadata {
    private String title;
    private String category;
    private List<String> tags;
    private boolean isPublic;
    // getters/setters
}

// 用户资料类
class UserProfile {
    private String username;
    private String bio;
    private LocalDate birthDate;
    // getters/setters
}

2.3 使用 @RequestPart 绑定到 Map 和 List

@RestController
@RequestMapping("/api/flexible")
public class FlexibleUploadController {
    // 绑定到 Map（接收 JSON 对象）
    @PostMapping(value = "/map", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithMap(
            @RequestPart("file") MultipartFile file,
            @RequestPart("attributes") Map<String, Object> attributes) {
        attributes.put("filename", file.getOriginalFilename());
        attributes.put("size", file.getSize());
        return "Processed with " + attributes.size() + " attributes";
    }

    // 绑定到 List（接收 JSON 数组）
    @PostMapping(value = "/list-json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithJsonList(
            @RequestPart("files") MultipartFile[] files,
            @RequestPart("tags") List<String> tags) {
        return String.format("Files: %d, Tags: %s", files.length, tags);
    }

    // 复杂的嵌套 JSON
    @PostMapping(value = "/nested", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithNestedJson(
            @RequestPart("document") MultipartFile document,
            @RequestPart("config") Map<String, Object> config) {
        return "Config: " + config;
    }
}

三、@RequestPart 的高级特性

3.1 验证 @RequestPart 参数

@RestController
@RequestMapping("/api/validated")
public class ValidatedUploadController {
    // 对 JSON 部分进行验证
    @PostMapping(value = "/validated", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<?> uploadValidated(
            @RequestPart("file") MultipartFile file,
            @Valid @RequestPart("metadata") FileMetadata metadata,
            BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            return ResponseEntity.badRequest()
                    .body(bindingResult.getAllErrors());
        }
        if (file.isEmpty()) {
            return ResponseEntity.badRequest()
                    .body("File cannot be empty");
        }
        return ResponseEntity.ok("Upload successful");
    }

    // 分组验证
    @PostMapping(value = "/group-validated", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadGroupValidated(
            @RequestPart("file") MultipartFile file,
            @Validated(FileMetadata.CreateGroup.class)
            @RequestPart("metadata") FileMetadata metadata) {
        return "Group validation passed";
    }
}

3.2 内容类型控制

@RestController
@RequestMapping("/api/content-type")
public class ContentTypeController {
    // 指定特定内容类型
    @PostMapping(value = "/specific", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadSpecificType(
            @RequestPart(value = "config", consumes = "application/json") AppConfig config,
            @RequestPart("file") MultipartFile file) {
        return "Config type: " + config.getClass().getSimpleName();
    }

    // 支持多种内容类型
    @PostMapping(value = "/flexible-type", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadFlexibleType(
            @RequestPart(value = "data", consumes = {"application/json", "application/xml"}) String data) {
        return "Received data: " + data.substring(0, Math.min(50, data.length()));
    }
}

3.3 使用 HttpEntity

@RestController
@RequestMapping("/api/entity")
public class EntityUploadController {
    // 使用 HttpEntity 获取完整部分信息
    @PostMapping(value = "/http-entity", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String uploadWithEntity(
            @RequestPart("file") MultipartFile file,
            @RequestPart("metadata") HttpEntity<FileMetadata> metadataEntity) {
        FileMetadata metadata = metadataEntity.getBody();
        HttpHeaders headers = metadataEntity.getHeaders();
        return String.format(
                "File: %s, Metadata: %s, Content-Type: %s",
                file.getOriginalFilename(), metadata.getTitle(), headers.getContentType()
        );
    }

    // 直接使用 RequestPart 的完整信息
    @PostMapping(value = "/full-control", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String fullControlUpload(
            @RequestPart("file") MultipartFile file,
            @RequestPart("config") RequestPartConfig configPart) {
        return "Processed with full control";
    }
}

四、@RequestPart 与 @RequestParam 对比示例

4.1 相同点和不同点演示

@RestController
@RequestMapping("/api/compare")
public class CompareController {
    // 场景1：上传文件 - 两者都可以
    @PostMapping(value = "/file-both", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String fileBoth(
            @RequestParam("file1") MultipartFile file1,
            @RequestPart("file2") MultipartFile file2) {
        return "Both work for files";
    }

    // 场景2：JSON数据 - 只有 @RequestPart 可以
    @PostMapping(value = "/json-only", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String jsonOnly(
            @RequestPart("data") UserData data) {
        return "Only @RequestPart works for JSON";
    }

    // 场景3：混合数据 - @RequestPart 的优势
    @PostMapping(value = "/mixed", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public String mixedUpload(
            @RequestPart("document") MultipartFile document,
            @RequestPart("metadata") DocumentMetadata metadata,
            @RequestParam("description") String description,
            @RequestParam("tags") String tags) {
        return String.format(
                "Document: %s, Metadata: %s, Desc: %s, Tags: %s",
                document.getOriginalFilename(), metadata.getTitle(), description, tags
        );
    }
}

class UserData {
    private String name;
    private int age;
    // getters/setters
}

class DocumentMetadata {
    private String title;
    private String author;
    private LocalDate createdDate;
    // getters/setters
}

4.2 前端请求示例

// 使用 FormData 发送混合数据
const formData = new FormData();

// 添加文件
formData.append('file', fileInput.files[0]);

// 添加 JSON 数据
const metadata = {
    title: 'My Document',
    author: 'John Doe',
    tags: ['important', 'urgent']
};
formData.append('metadata', JSON.stringify(metadata));

// 添加纯文本
formData.append('description', 'This is a document');

// 发送请求
fetch('/api/compare/mixed', {
    method: 'POST',
    body: formData
});

五、实际应用场景

5.1 电商商品上传

@RestController
@RequestMapping("/api/products")
public class ProductController {
    @PostMapping(value = "/create", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<ProductResponse> createProduct(
            @Valid @RequestPart("product") ProductDTO productDTO,
            @RequestPart("mainImage") MultipartFile mainImage,
            @RequestPart(value = "galleryImages", required = false) MultipartFile[] galleryImages,
            @RequestPart(value = "specifications", required = false) String specificationsJson) {
        // 保存商品基本信息
        Product product = productService.create(productDTO);

        // 保存主图
        String mainImageUrl = fileService.saveImage(mainImage);
        product.setMainImageUrl(mainImageUrl);

        // 保存图库图片
        if (galleryImages != null) {
            List<String> galleryUrls = Arrays.stream(galleryImages)
                    .map(fileService::saveImage)
                    .collect(Collectors.toList());
            product.setGalleryImageUrls(galleryUrls);
        }

        // 处理规格信息
        if (specificationsJson != null) {
            Map<String, Object> specs = objectMapper.readValue(
                    specificationsJson, new TypeReference<Map<String, Object>>() {}
            );
            product.setSpecifications(specs);
        }

        return ResponseEntity.ok(ProductResponse.success(product));
    }
}

// DTO类
class ProductDTO {
    @NotBlank
    private String name;
    @NotNull
    @DecimalMin("0.01")
    private BigDecimal price;
    @Min(0)
    private Integer stock;
    private String description;
    private Long categoryId;
    // getters/setters
}

5.2 用户注册带头像

@RestController
@RequestMapping("/api/users")
public class UserRegistrationController {
    @PostMapping(value = "/register", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<?> registerUser(
            @Valid @RequestPart("user") UserRegistrationRequest request,
            @RequestPart(value = "avatar", required = false) MultipartFile avatar,
            @RequestPart(value = "documents", required = false) List<MultipartFile> documents) {
        // 验证用户名唯一性
        if (userService.existsByUsername(request.getUsername())) {
            return ResponseEntity.badRequest()
                    .body(Map.of("error", "用户名已存在"));
        }

        // 创建用户
        User user = userService.createUser(request);

        // 保存头像
        if (avatar != null && !avatar.isEmpty()) {
            String avatarUrl = fileService.saveAvatar(avatar, user.getId());
            user.setAvatarUrl(avatarUrl);
        }

        // 保存证件照
        if (documents != null && !documents.isEmpty()) {
            List<Document> savedDocuments = documentService.saveDocuments(documents, user.getId());
            user.setDocuments(savedDocuments);
        }

        return ResponseEntity.ok(UserResponse.fromEntity(user, jwtService.generateToken(user)));
    }
}

5.3 批量导入数据

@RestController
@RequestMapping("/api/import")
public class ImportController {
    @PostMapping(value = "/bulk", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public BulkImportResponse bulkImport(
            @RequestPart("template") MultipartFile templateFile,
            @RequestPart("config") ImportConfig config,
            @RequestPart("mapping") Map<String, String> fieldMapping,
            @RequestParam("dryRun") boolean dryRun) {
        // 验证文件类型
        if (!templateFile.getOriginalFilename().endsWith(".xlsx")) {
            throw new IllegalArgumentException("只支持 Excel 文件");
        }

        // 读取模板文件
        List<Map<String, Object>> data = excelReader.read(templateFile);

        // 根据配置处理数据
        ImportResult result = importService.process(data, config, fieldMapping, dryRun);

        return BulkImportResponse.builder()
                .totalCount(result.getTotalCount())
                .successCount(result.getSuccessCount())
                .failedCount(result.getFailedCount())
                .errors(result.getErrors())
                .dryRun(dryRun)
                .build();
    }
}

六、常见问题和解决方案

6.1 问题1：@RequestPart 与 @RequestParam 混淆

// 错误示例：尝试用 @RequestParam 接收 JSON
@PostMapping(value = "/wrong", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String wrongExample(@RequestParam("jsonData") UserData data) {
    return "This won't work";
}

// 正确示例：使用 @RequestPart
@PostMapping(value = "/correct", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String correctExample(@RequestPart("jsonData") UserData data) {
    return "This works";
}

6.2 问题2：缺少 consumes 属性

// 可能的问题：忘记指定 consumes
@PostMapping("/implicit")
public String implicit(@RequestPart("file") MultipartFile file) {
    return "Implicit";
}

// 最佳实践：明确指定
@PostMapping(value = "/explicit", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String explicit(@RequestPart("file") MultipartFile file) {
    return "Explicit is better";
}

6.3 问题3：前端没有正确设置 Content-Type

@RestControllerAdvice
public class MultipartExceptionHandler {
    @ExceptionHandler(MultipartException.class)
    public ResponseEntity<?> handleMultipartException(
            MultipartException ex, HttpServletRequest request) {
        String message = "文件上传失败: ";
        if (ex instanceof MissingServletRequestPartException) {
            message += "缺少必要的数据部分";
        } else if (ex instanceof MaxUploadSizeExceededException) {
            message += "文件大小超过限制";
        } else {
            message += ex.getMessage();
        }

        // 检查是否是 Content-Type 问题
        String contentType = request.getContentType();
        if (contentType == null || !contentType.contains("multipart/form-data")) {
            message += "。请使用 multipart/form-data 格式";
        }

        return ResponseEntity.badRequest()
                .body(Map.of("error", message));
    }
}

6.4 配置建议

spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 10MB
      max-request-size: 100MB
      file-size-threshold: 2MB
      location: ${java.io.tmpdir}

七、总结对比表

八、选择建议

使用 @RequestPart 当：

1. 需要上传文件并且同时发送 JSON 数据
2. 请求中包含多种不同类型的内容（JSON、XML、文件等）
3. 需要对非文件部分进行 Bean Validation 验证
4. 需要获取部分的完整信息（如请求头）

使用 @RequestParam 当：

1. 只上传文件，没有复杂的结构化数据
2. 只有简单的键值对参数
3. 需要向后兼容旧的表单提交

最佳实践：

// 混合使用示例
@PostMapping(value = "/best-practice", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String bestPractice(
        @RequestPart("document") MultipartFile document,
        @RequestPart("metadata") DocumentMetadata metadata,
        @RequestParam("description") String description,
        @RequestParam(value = "tags", required = false) String tags) {
    return "Processed successfully";
}

记住：@RequestPart 是 @RequestParam 的增强版本，专门为 multipart/form-data 请求设计，支持更复杂的数据绑定场景。