JAVA Rest API 返回空对象？ObjectMapper 默认配置与序列化策略调整

JAVA Rest API 返回空对象？ObjectMapper 默认配置与序列化策略调整

大家好，今天我们来聊聊一个在开发REST API时经常会遇到的问题：API返回了空对象。这看起来很简单，但背后可能涉及到ObjectMapper的默认配置，以及我们如何根据实际需求调整序列化策略。希望通过今天的讲解，大家能够更深入地理解ObjectMapper，并能灵活地处理各种序列化场景。

1. 空对象问题的表象与根源

当我们说API返回空对象，通常指的是API在客户端接收到的JSON数据是{}。 这种情况可能由多种原因造成，但最常见的根源在于：

• 对象本身确实为空： 我们的代码逻辑可能导致某个对象在被序列化之前，其所有字段都为null或者对应类型的默认值（例如int为0，boolean为false）。

• ObjectMapper的默认行为： ObjectMapper在默认配置下，会将所有null值的字段都序列化进JSON。这意味着，如果一个对象的所有字段都是null，那么序列化结果就是{}。

• 序列化策略的误用： 我们可能使用了错误的注解或者配置，导致ObjectMapper忽略了某些字段，或者强制将某些字段序列化为null。

2. ObjectMapper 的默认行为剖析

ObjectMapper是Jackson库的核心组件，负责Java对象和JSON之间的转换。 了解其默认行为对于解决空对象问题至关重要。

• 默认配置： ObjectMapper在创建时，会应用一系列默认配置。这些配置决定了它如何处理各种数据类型，如何处理null值，以及如何处理日期和时间等特殊类型。

• Null值处理： 默认情况下，ObjectMapper会将所有字段，包括值为null的字段，都序列化到JSON中。这意味着，即使一个字段的值是null，它仍然会出现在JSON中，其值为null。

• 空Bean处理： 如果一个JavaBean的所有属性都为null，ObjectMapper默认仍然会将其序列化为一个空的JSON对象{}。

3. 常见场景与解决方案

接下来，我们通过几个具体的场景，来看看如何解决API返回空对象的问题。

场景一：对象本身为空，但希望返回null而不是{}

假设我们有一个User类：

public class User {
    private String name;
    private int age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

如果一个User对象的所有字段都是null，例如：

User user = new User(); // name 和 age 都为 null

使用默认的ObjectMapper序列化后，会得到{}。 但有时我们希望在这种情况下，直接返回null。

解决方案：使用SerializationFeature.FAIL_ON_EMPTY_BEANS

我们可以通过禁用SerializationFeature.FAIL_ON_EMPTY_BEANS来实现这个目标。这个特性默认是启用的，它会在ObjectMapper遇到一个所有属性都为null的Bean时抛出一个异常。禁用它可以让ObjectMapper在这种情况下返回null。

ObjectMapper mapper = new ObjectMapper();
mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);

User user = new User();
try {
    String json = mapper.writeValueAsString(user);
    System.out.println(json); // 输出: null
} catch (JsonProcessingException e) {
    e.printStackTrace();
}

场景二：忽略值为null的字段

在某些情况下，我们不希望JSON中包含值为null的字段。例如，我们只想返回实际有值的字段，以减少JSON的大小。

解决方案：使用JsonInclude.Include.NON_NULL

我们可以使用@JsonInclude注解来控制ObjectMapper如何处理null值。JsonInclude.Include.NON_NULL表示只包含非null的字段。

import com.fasterxml.jackson.annotation.JsonInclude;

@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private String name;
    private Integer age; // 注意这里使用Integer，而不是int，以便可以为null

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

现在，如果name和age都为null，序列化后的JSON将是{}。如果只有age为null，序列化后的JSON将只包含name字段。

User user = new User();
user.setName("Alice");

ObjectMapper mapper = new ObjectMapper();
try {
    String json = mapper.writeValueAsString(user);
    System.out.println(json); // 输出: {"name":"Alice"}
} catch (JsonProcessingException e) {
    e.printStackTrace();
}

场景三：全局配置null值处理策略

如果我们需要对所有JavaBean都应用相同的null值处理策略，可以使用ObjectMapper的全局配置。

解决方案：配置setDefaultPropertyInclusion

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;

public class ObjectMapperConfig {
    public static ObjectMapper createObjectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        // 全局配置：忽略null值的字段
        mapper.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);
        // 禁用FAIL_ON_EMPTY_BEANS，使空bean返回null
        mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);

        return mapper;
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = createObjectMapper();
        User user = new User();
        String json = mapper.writeValueAsString(user);
        System.out.println(json); // 输出: null

        user.setName("Bob");
        json = mapper.writeValueAsString(user);
        System.out.println(json); // 输出: {"name":"Bob"}
    }
}

在这个例子中，我们创建了一个自定义的ObjectMapper，并设置了全局的null值处理策略。所有使用这个ObjectMapper序列化的JavaBean都会自动忽略null值的字段。

场景四：自定义序列化器

有时，默认的序列化策略无法满足我们的需求。例如，我们可能需要对日期格式进行自定义，或者需要对某些字段进行加密处理。

解决方案：使用JsonSerializer

我们可以通过实现JsonSerializer接口来创建自定义的序列化器。

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import java.io.IOException;
import java.text.SimpleDateFormat;
import java.util.Date;

public class CustomDateSerializer extends JsonSerializer<Date> {
    private static final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");

    @Override
    public void serialize(Date date, JsonGenerator gen, SerializerProvider provider) throws IOException {
        String formattedDate = dateFormat.format(date);
        gen.writeString(formattedDate);
    }
}

然后，我们可以使用@JsonSerialize注解将自定义的序列化器应用到相应的字段上。

import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import java.util.Date;

public class Event {
    private String name;
    @JsonSerialize(using = CustomDateSerializer.class)
    private Date eventDate;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Date getEventDate() {
        return eventDate;
    }

    public void setEventDate(Date eventDate) {
        this.eventDate = eventDate;
    }
}

现在，eventDate字段将会使用我们自定义的CustomDateSerializer进行序列化。

场景五：使用 Spring Boot 的全局配置

如果项目是基于 Spring Boot 构建的，我们可以通过配置 application.properties 或 application.yml 文件来全局配置 ObjectMapper。

*解决方案：配置 `spring.jackson.` 属性**

spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS=false  #禁用将日期序列化为时间戳
spring.jackson.default-property-inclusion=non_null # 全局忽略null值的字段
spring.jackson.serialization.FAIL_ON_EMPTY_BEANS=false # 禁用空bean抛出异常

这些配置会自动应用到 Spring Boot 自动配置的 ObjectMapper 上。

4. ObjectMapper 常用配置项

为了更全面地理解ObjectMapper的配置，我们整理了一些常用的配置项，并用表格形式呈现。

配置项	类型	描述
SerializationFeature.INDENT_OUTPUT	boolean	是否格式化输出JSON，使其更易读。
SerializationFeature.WRITE_DATES_AS_TIMESTAMPS	boolean	是否将日期序列化为时间戳。默认情况下，日期会被序列化为ISO-8601格式的字符串。
DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES	boolean	如果JSON中包含JavaBean中不存在的属性，是否抛出异常。
JsonInclude.Include.NON_NULL	enum	控制ObjectMapper如何处理null值。NON_NULL表示只包含非null的字段，NON_EMPTY表示只包含非null且非空的字段（例如，空字符串、空集合）。
PropertyNamingStrategy	PropertyNamingStrategy	用于自定义JavaBean属性和JSON属性之间的映射策略。例如，可以将驼峰命名的JavaBean属性转换为下划线命名的JSON属性。

5. 代码示例：完整的Spring Boot REST API

为了更好地演示如何在实际项目中使用ObjectMapper，我们提供一个完整的Spring Boot REST API示例。

// User.java
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;

@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private Long id;
    private String name;
    private String email;
}

// UserController.java
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // 模拟从数据库获取User对象
        if (id == 1) {
            User user = new User();
            user.setId(1L);
            user.setName("John Doe");
            user.setEmail("[email protected]");
            return user;
        } else if (id == 2) {
            User user = new User();
            user.setId(2L);
            user.setName("Jane Doe");
            return user; // email 为 null，将不会出现在 JSON 中
        } else {
            return null; // 返回 null，Spring MVC 会将其转换为 204 No Content
        }
    }
}

// Spring Boot Application 类
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

在这个例子中，我们创建了一个简单的REST API，用于获取用户信息。我们使用了@JsonInclude(JsonInclude.Include.NON_NULL)注解来忽略null值的字段。如果email字段为null，它将不会出现在JSON中。

同时，如果 getUser 方法返回 null, Spring MVC 会自动将其转换成 204 No Content 响应，而不是 {}。

6. 调试技巧

当遇到空对象问题时，可以尝试以下调试技巧：

• 打印对象： 在序列化之前，打印对象的各个字段的值，确认对象是否确实为空。
• 查看ObjectMapper配置： 确认ObjectMapper的配置是否正确，例如是否启用了FAIL_ON_EMPTY_BEANS特性。
• 使用断点调试： 在序列化过程中设置断点，查看ObjectMapper是如何处理null值的。
• 查看JSON输出： 使用JSON格式化工具查看JSON输出，确认JSON的结构是否符合预期。

总结：掌握ObjectMapper，灵活应对序列化

通过今天的讲解，我们深入了解了ObjectMapper的默认行为，以及如何通过配置和自定义序列化器来解决API返回空对象的问题。希望大家能够灵活运用这些知识，更好地处理各种序列化场景。