Spring Boot 应用返回 HTTP 415 错误的完整排查与解决方案

本文详解 spring mvc 中出现 http 415 unsupported media type 错误的根本原因，重点说明 `@requestbody` 接收 json 数据时对请求头、配置及数据结构的严格要求，并提供 postman 配置、控制器优化和常见陷阱的实操指南。

HTTP 415 Unsupported Media Type 是一个典型的客户端请求错误，它并非表示后端逻辑异常，而是服务端明确拒绝了当前请求的媒体类型（Media Type）。在你的 Spring Boot REST 控制器中，@PostMapping 方法使用 @RequestBody GiftCertificate gc 接收 JSON 数据，但服务器却返回 415 —— 这说明 Spring 的 HttpMessageConverter（特别是 MappingJackson2HttpMessageConverter）未能成功将请求体反序列化为 Java 对象。根本原因通常有以下三类，需逐一验证：

✅ 1. Postman 请求头缺失或错误（最常见！）

即使你“尝试过设置 Content-Type”，也请严格确认：

• 必须显式添加请求头：Content-Type: application/json
• 不能仅依赖 Body → raw → JSON 模式自动设置（某些 Postman 版本或环境可能未正确注入）；
• 禁止同时存在冲突头（如 Content-Type: text/plain 或未设置任何 Content-Type）。

? 正确 Postman 配置步骤：
① 选择 POST 方法，URL 填写 http://localhost:8080/certificate；
② 切换到 Headers 标签页，手动添加：

Key: Content-Type  
Value: application/json

③ 切换到 Body → raw → JSON，输入有效 JSON（注意字段名需与 Java Bean 完全匹配）：

{
  "name": "sas",
  "description": "sasasas",
  "price": 12,
  "duration": 12
}

✅ 2. Java 实体类缺少必要支持

确保 GiftCertificate 类满足 Jackson 反序列化要求：

剪映专业版

一款全能易用的桌面端剪辑软件

下载

• 提供无参构造函数（默认已有则无需额外声明）；
• 字段命名与 JSON key 严格一致（或通过 @JsonProperty("xxx") 显式映射）；
• 建议添加 Lombok 注解简化代码（避免手写 getter/setter 遗漏）：

import lombok.Data;

@Data
public class GiftCertificate {
    private String name;
    private String description;
    private BigDecimal price; // 推荐用 BigDecimal 替代 double/float
    private Integer duration;
}

⚠️ 注意：若 price 字段定义为 double，而 JSON 中传 "price": 12（整数），Jackson 默认可兼容；但若传 "price": "12"（字符串），则会因类型不匹配导致 400 Bad Request —— 此时 415 不会出现，但需警惕数据一致性。

✅ 3. Spring 配置与依赖检查

• 确认项目已引入 spring-boot-starter-web（自动包含 Jackson 依赖）；
• 检查 application.properties 中未禁用 Jackson：

  # 确保以下配置未被设为 false
  spring.jackson.serialization.write-dates-as-timestamps=false

• 若自定义了 WebMvcConfigurer，请确认未意外移除 MappingJackson2HttpMessageConverter。

? 进阶建议：增强控制器健壮性

为快速定位问题，可临时添加日志与更明确的响应：

@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE) // 显式声明 consumes
public ResponseEntity> createCertificate(@RequestBody GiftCertificate gc) {
    try {
        gcs.createCertificate(gc);
        Map response = Map.of(
            "status", "success",
            "code", HttpStatus.CREATED.value()
        );
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(Map.of("error", "Invalid request data", "message", e.getMessage()));
    }
}

? 小结：HTTP 415 几乎总是由 客户端未发送正确的 Content-Type 头 引起。优先用 Postman 严格验证请求头，再排查实体类结构与 Jackson 配置。记住：Spring 的 @RequestBody 机制是“契约式”的——客户端必须精确承诺媒体类型，服务端才愿意解析其内容。