Spring集成Jackson无法转换JSON及返回JSONObject问题求助

我之前也碰到过类似的Spring项目JSON返回异常的问题，尤其是依赖冲突导致的Jackson失效，给你几个排查和解决的思路：

1. 确认Jackson核心依赖的正确引入 #

如果是Spring Boot项目，优先使用官方提供的web starter，它已经内置了适配好的Jackson依赖，能避免很多版本冲突问题：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

如果你单独引入了com.fasterxml.jackson的包，要确保jackson-core、jackson-databind、jackson-annotations这三个核心包的版本完全一致，版本不一致很容易导致序列化失败。

2. 排查依赖树找出冲突包 #

用Maven命令生成完整的依赖树，定位可能和Jackson冲突的第三方JSON库：

mvn dependency:tree

重点留意这些可能的冲突源：

• 旧版的Jackson（org.codehaus.jackson开头的包）
• 其他JSON处理库（比如Gson、Fastjson）
• 某些第三方依赖间接引入的JSON相关包

如果发现冲突包，在对应的依赖中排除它，比如排除旧版Jackson：

<dependency>
    <groupId>你的依赖组ID</groupId>
    <artifactId>你的依赖包ID</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.codehaus.jackson</groupId>
            <artifactId>jackson-mapper-asl</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.codehaus.jackson</groupId>
            <artifactId>jackson-core-asl</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 检查Spring MVC消息转换器配置 #

有时候自定义的WebMvc配置会覆盖默认的Jackson消息转换器，导致JSON序列化失效。检查项目中是否有实现WebMvcConfigurer的配置类，尤其是重写configureMessageConverters方法的地方：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 不要直接清空converters列表，否则会丢失默认的Jackson转换器
        // 正确做法是添加自定义转换器，或者调用父类方法保留默认配置
        WebMvcConfigurer.super.configureMessageConverters(converters);
        
        // 如果需要自定义Jackson配置，可以这样做
        MappingJackson2HttpMessageConverter jacksonConverter = new MappingJackson2HttpMessageConverter();
        ObjectMapper objectMapper = new ObjectMapper();
        // 添加自定义配置，比如日期格式化、空值处理等
        objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        jacksonConverter.setObjectMapper(objectMapper);
        converters.add(jacksonConverter);
    }
}

4. 用简单接口验证Jackson是否正常工作 #

先抛开JSONObject，写一个返回普通POJO的测试接口，验证Jackson基础功能是否正常：

@RestController
public class TestController {
    @GetMapping("/test-json")
    public UserDTO testJson() {
        UserDTO user = new UserDTO();
        user.setUsername("test-user");
        user.setEmail("test@example.com");
        return user;
    }

    // 记得添加getter/setter，或者用Lombok的@Data注解简化
    static class UserDTO {
        private String username;
        private String email;

        public String getUsername() { return username; }
        public void setUsername(String username) { this.username = username; }
        public String getEmail() { return email; }
        public void setEmail(String email) { this.email = email; }
    }
}

如果这个接口能正常返回JSON，说明Jackson本身没问题，问题出在你直接返回JSONObject的逻辑上。

5. 正确处理JSONObject的返回 #

如果一定要返回JSONObject，分两种情况处理：

• 如果你用的是Jackson自带的ObjectNode，直接返回即可，Spring默认支持：

@GetMapping("/jackson-json")
public ObjectNode getJacksonJson() {
    ObjectMapper mapper = new ObjectMapper();
    ObjectNode node = mapper.createObjectNode();
    node.put("status", "success");
    node.put("data", "test-data");
    return node;
}

• 如果你用的是org.json.JSONObject（Java原生JSON包），Spring默认没有对应的消息转换器，你可以转成String返回，并指定响应类型：

@GetMapping(value = "/org-json", produces = MediaType.APPLICATION_JSON_VALUE)
public String getOrgJson() {
    JSONObject json = new JSONObject();
    json.put("status", "success");
    json.put("data", "test-data");
    return json.toString();
}

内容的提问来源于stack exchange，提问作者J. Doe