向Jersey Rest端点发送内容时出现Error 415（不支持的媒体类型）问题

阿华AIGC实验室

2026-5-19

解决Jersey接收Multipart Form Data时的415 Unsupported Media Type错误

我帮你梳理一下这个问题的常见原因和解决方案，毕竟我见过不少开发者踩过这个坑：

1. 最容易忽略的：缺少Multipart支持依赖

Jersey本身不会默认处理multipart/form-data请求，必须额外引入jersey-media-multipart依赖，并且注册对应的Feature。

如果用Maven，先加依赖（注意版本要和你的Jersey核心版本完全一致）：

<dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-multipart</artifactId>
    <version>你的Jersey版本号</version>
</dependency>

然后在你的Jersey配置类里注册MultiPartFeature：

public class MyJerseyConfig extends ResourceConfig {
    public MyJerseyConfig() {
        // 注册Multipart支持
        register(MultiPartFeature.class);
        // 扫描你的资源类所在包
        packages("com.your.project.resources");
    }
}

2. 前端Ajax请求配置错误

很多时候问题出在前端，特别是手动设置Content-Type的时候。浏览器会自动为FormData生成正确的boundary参数，但如果你手动指定contentType: 'multipart/form-data'，会丢失这个关键参数，导致后端无法解析。

错误示例：

$.ajax({
    url: '/api/fileupload',
    type: 'POST',
    contentType: 'multipart/form-data', // 这里手动设置会导致缺少boundary
    data: formData,
    success: function(res) { /* ... */ }
});

正确的写法应该让浏览器自动处理：

$.ajax({
    url: '/api/fileupload',
    type: 'POST',
    contentType: false, // 禁用手动设置，让浏览器自动生成正确的Content-Type
    processData: false, // 不要处理FormData，避免破坏文件结构
    data: formData,
    success: function(res) { /* ... */ }
});

你可以用浏览器开发者工具的Network标签，查看实际发送的请求头，确认Content-Type是不是类似multipart/form-data; boundary=----WebKitFormBoundaryxxxxxx这样的格式，如果没有boundary，那就是前端配置的问题。

3. 后端方法参数绑定不完整

你的方法里只写了FormDataContentDisposition，通常还需要对应的InputStream来接收文件的实际内容。如果只传文件的元数据（比如文件名），而没有文件流，可能会导致参数绑定失败，间接触发415错误。

调整后端方法：

@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
@Path("/fileupload")
public Response uploadFile(
    @FormDataParam("file") InputStream fileStream, // 接收文件内容
    @FormDataParam("file") FormDataContentDisposition fileDisposition) {
    
    // 示例：获取文件名
    String fileName = fileDisposition.getFileName();
    // 这里写你的文件保存/处理逻辑
    
    return Response.ok("文件上传成功：" + fileName).build();
}