如何在multipart/form-data响应中返回批量附件关联元数据？

一、现有方案评价 #

方案1：将key设为包含双ID的JSON对象 #

不推荐这种方式。multipart/form-data的字段key本质是字符串，虽然可以强行传入JSON格式的字符串，但不符合表单字段的常规设计规范，客户端拼接和服务器解析时都容易出错，会增加双方的处理复杂度，后续调试和维护成本高。

方案2：拆分端点，单次处理单个BatchTechnicalRecord的附件 #

这个方案符合RESTful设计原则，端点/api/batches/technical-records/{ID_BATCH_TECHNICAL_RECORD}/attachments清晰定位到特定批次的附件资源，逻辑简单直接，服务器端的参数校验、业务处理和异常排查都更方便。缺点是客户端需要分多次请求，但如果批量规模不大，这种方案的可靠性和可维护性优势明显，完全可以采用。

二、更高效的标准替代方案 #

如果需要保留批量上传的效率，推荐在multipart/form-data响应中加入一个结构化的JSON部分，用来返回BatchTechnicalRecord ID与对应生成的BatchTechnicalRecordAttachment ID列表的映射关系。

具体实现思路：

• 服务器处理完所有上传文件和关联逻辑后，构造一个JSON对象，键为BatchTechnicalRecord的ID（字符串或数字类型），值为对应生成的BatchTechnicalRecordAttachment ID数组。
• 将这个JSON作为multipart响应的一个独立part（Content-Type设为application/json），客户端可以优先解析这个part，直接获取ID映射关系。

这种方式既支持批量上传的高效性，又返回了清晰、标准的关联数据，完全符合HTTP规范和API设计的最佳实践。

三、Jakarta EE 10下的代码示例 #

基于Wildfly服务器，你可以这样实现响应构造：

import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.MultipartEntityBuilder;
import jakarta.ws.rs.core.Response;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Path("/api/batches/technical-records/attachments/batch")
public class BatchAttachmentResource {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @POST
    @Produces(MediaType.MULTIPART_FORM_DATA)
    public Response batchUploadAttachments() {
        // 省略文件接收、关联处理、保存逻辑...
        // 假设处理后得到映射关系：
        Map<Long, List<Long>> idMapping = new HashMap<>();
        idMapping.put(1L, List.of(101L, 102L, 103L));
        idMapping.put(2L, List.of(201L));

        // 构造multipart响应
        MultipartEntityBuilder builder = MultipartEntityBuilder.create();
        try {
            // 添加JSON映射part
            builder.addPart("idMapping", objectMapper.writeValueAsString(idMapping),
                    MediaType.APPLICATION_JSON_TYPE);
            // 如果需要，可以额外返回其他part（比如上传成功的文件元数据等）
        } catch (Exception e) {
            return Response.status(Response.Status.INTERNAL_SERVER_ERROR).build();
        }

        return Response.ok(builder.build()).build();
    }
}

客户端解析时，只需提取idMapping这个part的内容，即可得到每个BatchTechnicalRecord对应的所有附件关联ID。

内容的提问来源于stack exchange，提问作者Pedro Vitor