Spring Boot 3使用Projection查询后接口返回媒体类型不兼容异常问题

问题场景 #

使用Spring Boot 3通过Projection（含嵌套子接口UserConnexion/CatogoryUserCode）实现实体部分字段查询，编写@Query关联查询后，调用GET接口/user/{id}时触发错误：org.springframework.web.HttpMediaTypeNotAcceptableException: No acceptable representation

排查与解决方案 #

1. 检查投影接口的序列化兼容性 #

Spring Boot默认用Jackson序列化对象，投影接口必须严格遵循JavaBean getter规范：

• 所有暴露字段的方法必须以get开头（比如getId()、getCategoryCode()），Jackson依赖这些方法提取字段值；
• 嵌套子接口CatogoryUserCode同样要符合getter命名规则，不能存在非getter风格的方法。

2. 验证请求的Accept头匹配度 #

该错误常因请求期望的响应格式与接口实际能返回的格式不匹配导致：

• 测试时明确设置请求头Accept: application/json，确保客户端期望JSON格式；
• 若需支持多格式，确认spring-boot-starter-web依赖已引入（默认包含Jackson JSON转换器）。

3. 规范空值处理逻辑 #

即使业务层处理了空值，不当的返回值仍可能引发序列化问题：

• 确保findLigtUserById方法无数据时返回Optional.empty()，而非直接返回null；
• 接口层用ResponseEntity包装返回值，明确处理空场景：

  @GetMapping("/user/{id}")
  public ResponseEntity<UserConnexion> getUser(@PathVariable Long id) {
      return userManager.findLigtUserById(id)
          .map(ResponseEntity::ok)
          .orElse(ResponseEntity.notFound().build());
  }
  

4. 修正@Query的映射逻辑 #

如果查询结果无法正确映射到投影接口，会导致返回对象类型异常：

• 检查@Query语句，确保返回字段与投影接口的getter方法完全对应。比如嵌套投影需返回子接口所需的所有字段：

  @Query("SELECT u.id as id, u.username as username, c.code as categoryCode, c.name as categoryName " +
         "FROM User u JOIN u.category c WHERE u.id = :id")
  Optional<UserConnexion> findLightUserById(@Param("id") Long id);
  

• 投影接口示例需对应上述查询的返回字段：

  public interface UserConnexion {
      Long getId();
      String getUsername();
      CatogoryUserCode getCategory();
  
      interface CatogoryUserCode {
          String getCategoryCode();
          String getCategoryName();
      }
  }
  

5. 适配Spring Boot 3的序列化配置 #

Spring Boot 3基于Jakarta EE，Jackson配置可能存在版本差异：

• 确认项目依赖的Jackson版本为2.15+（与Spring Boot 3兼容）；
• 若自定义Jackson配置，避免禁用接口序列化相关特性，比如确保MapperFeature.DEFAULT_VIEW_INCLUSION未被关闭，DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES设置合理。

内容的提问来源于stack exchange，提问作者robert trudel