防止Jackson序列化空值必填字段的方法

1. 问题背景与现有方案的局限性

在Java应用中，我们经常需要将POJO（Plain Old Java Object）序列化为JSON格式进行数据传输。Jackson是一个功能强大且广泛使用的JSON处理库。然而，在某些业务场景下，我们可能对JSON数据有严格的完整性要求：如果POJO中的某个或多个“必填”字段为null，我们不希望Jackson继续进行序列化，而是立即停止并报错，以确保输出的JSON始终是完整且有效的。

Jackson提供了一些内置机制来处理空值，例如@JsonInclude(JsonInclude.Include.NON_NULL)可以忽略值为null的字段，或者@JsonProperty(required = true)用于在反序列化（JSON转POJO）时校验必填字段是否存在。但是，这些机制并不能满足在序列化（POJO转JSON）阶段对必填字段进行空值校验并阻止整个对象序列化的需求。@JsonProperty(required = true)主要作用于反序列化，即使字段被标记为required，如果其在POJO中的值为null，Jackson在序列化时仍会将其序列化为JSON中的null，而不是中断进程。

2. 解决方案：自定义Jackson序列化器

要实现在序列化阶段对必填字段进行空值校验并阻止整个对象序列化，最有效的方法是创建Jackson的自定义序列化器。通过扩展JsonSerializer类，我们可以完全控制对象的序列化过程，并在其中嵌入自定义的验证逻辑。

2.1 创建自定义序列化器

自定义序列化器需要继承com.fasterxml.jackson.databind.JsonSerializer，其中T是你希望处理的POJO类型。最核心的方法是serialize(T value, JsonGenerator gen, SerializerProvider serializers)。

在serialize方法中，你可以：

1. 定义校验逻辑：检查传入的value对象中所有被认为是“必填”的字段是否为null。
2. 中断序列化：如果任何必填字段为null，则抛出com.fasterxml.jackson.core.JsonGenerationException异常，从而中断整个序列化过程。
3. 执行正常序列化：如果所有必填字段都有效（非null），则手动将POJO的每个字段写入JsonGenerator。这需要你显式地调用gen.writeString(), gen.writeNumber(), gen.writeObject()等方法来构建JSON结构。

以下是一个针对BigJsonDto类的自定义序列化器示例：

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.core.JsonGenerationException;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;
import java.io.IOException;
import java.util.Objects;
import java.util.function.Predicate;
import java.util.stream.Stream;

// 假设 BigJsonDto 是你的数据传输对象
// @Builder
// @Data
// public class BigJsonDto {
//     private String field1;
//     private String field2;
//     private String field3;
//     // ... 其他字段
//     private String fieldN;
// }

public class BigJsonDtoSerializer extends JsonSerializer {

    // 定义一个Predicate，用于检查BigJsonDto实例是否无效（即存在空值的必填字段）
    public static final Predicate IS_NOT_VALID =
        dto -> Stream.of(dto.getField1(), // 假设field1、field2、field3是必填字段
                         dto.getField2(),
                         dto.getField3())
            .anyMatch(Objects::isNull); // 只要有一个字段为null，就返回true

    @Override
    public void serialize(BigJsonDto value, JsonGenerator gen,
                          SerializerProvider serializers) throws IOException {

        // 1. 执行验证逻辑
        if (IS_NOT_VALID.test(value)) {
            // 如果对象无效，抛出异常以阻止序列化
            throw new JsonGenerationException("BigJsonDto instance is not valid: required fields are null", gen);
        }

        // 2. 如果验证通过，手动序列化对象的所有字段
        // 注意：这里需要你手动将每个字段写入JsonGenerator
        gen.writeStartObject(); // 开始写入JSON对象

        gen.writeFieldName("field1");
        gen.writeString(value.getField1());

        gen.writeFieldName("field2");
        gen.writeString(value.getField2());

        gen.writeFieldName("field3");
        gen.writeString(value.getField3());

        // ... 根据BigJsonDto的实际字段，继续写入其他字段
        // 例如：
        // gen.writeFieldName("fieldN");
        // gen.writeString(value.getFieldN());

        gen.writeEndObject(); // 结束写入JSON对象
    }

    /**
     * 此方法仅在通过Module注册序列化器时需要重写。
     * 它返回此序列化器处理的类型。
     */
    @Override
    public Class handledType() {
        return BigJsonDto.class;
    }
}

注意事项：

• 在serialize方法中，如果验证通过，你必须手动将POJO的所有字段写入JsonGenerator。Jackson不会自动为你完成这一步。这意味着你需要根据字段的类型调用gen.writeString(), gen.writeNumber(), gen.writeBoolean(), gen.writeObject()等方法。
• handledType()方法只有在将序列化器作为Jackson模块的一部分进行注册时才需要实现。如果通过注解方式注册，则不需要重写此方法。

2.2 注册自定义序列化器

自定义序列化器创建完成后，需要将其注册到Jackson的ObjectMapper中，以便Jackson知道何时使用它。有两种主要方法：

方法一：使用@JsonSerialize注解（针对特定类）

这是最直接的方法，通过在你的POJO类上添加@JsonSerialize注解，并指定using属性为你的自定义序列化器类。

import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import lombok.Builder;
import lombok.Data;

@Data
@Builder
@JsonSerialize(using = BigJsonDtoSerializer.class) // 指定使用自定义序列化器
public class BigJsonDto {
    private String field1;
    private String field2;
    private String field3;
    private String fieldN; // 示例字段
}

这种方法的优点是简单明了，直接将序列化逻辑绑定到特定的POJO类。缺点是如果有很多类需要类似的校验，每个类都需要添加注解。

方法二：通过Jackson模块进行全局注册

如果你有多个自定义序列化器，或者希望更灵活地管理序列化器，可以通过创建SimpleModule并将其注册到ObjectMapper来实现。这种方式允许你集中管理多个序列化器和反序列化器，并且无需修改POJO类上的注解。

import com.fasterxml.jackson.core.Version;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;
import java.util.List;
import java.util.Map;

public class JacksonConfig {

    public static ObjectMapper createObjectMapperWithCustomSerializer() {
        ObjectMapper mapper = new ObjectMapper();

        // 创建一个SimpleModule实例
        SimpleModule mySerializationModule = new SimpleModule(
            "MySerializationModule", // 模块名称
            new Version(1, 0, 0, null, "com.example", "my-jackson-module"), // 模块版本信息
            Map.of(),                           // 反序列化器列表 (本例中为空)
            List.of(new BigJsonDtoSerializer()) // 序列化器列表
        );

        // 将模块注册到ObjectMapper
        mapper.registerModule(mySerializationModule);
        return mapper;
    }

    // 如果你使用Spring Boot，可以通过将SimpleModule作为Bean来自动注册
    /*
    @Configuration
    public class JacksonModuleConfig {
        @Bean
        public SimpleModule myCustomSerializationModule() {
            SimpleModule module = new SimpleModule(
                "MySerializationModule",
                new Version(1, 0, 0, null, "com.example", "my-jackson-module")
            );
            module.addSerializer(BigJsonDto.class, new BigJsonDtoSerializer()); // 添加特定类的序列化器
            return module;
        }
    }
    */
}

通过模块注册的优点是：

• 集中管理：所有自定义序列化器可以在一个地方注册。
• 解耦：POJO类无需知道具体的序列化器实现，提高了代码的解耦性。
• 灵活性：可以在运行时动态添加或移除序列化器。
• handledType()：当通过模块注册时，自定义序列化器中的handledType()方法必须正确实现，以告知Jackson该序列化器处理哪种类型。

3. 使用示例

现在，我们来看一个完整的示例，演示如何使用自定义序列化器来阻止包含空值的对象被序列化：

import com.fasterxml.jackson.core.JsonGenerationException;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Builder;
import lombok.Data;
import com.fasterxml.jackson.databind.annotation.JsonSerialize; // 如果使用注解方式

public class SerializationDemo {

    // 假设BigJsonDto和BigJsonDtoSerializer已按上述定义

    public static void main(String[] args) {
        ObjectMapper mapper = new ObjectMapper();

        // 方式一：如果BigJsonDto类上使用了@JsonSerialize注解，则直接使用默认ObjectMapper即可
        // 或者
        // 方式二：如果通过模块注册，则需要使用配置了模块的ObjectMapper
        // ObjectMapper mapper = JacksonConfig.createObjectMapperWithCustomSerializer();

        // 示例1：有效对象 - 成功序列化
        BigJsonDto validDto = BigJsonDto.builder()
            .field1("value1")
            .field2("value2")
            .field3("value3")
            .fieldN("valueN")
            .build();

        try {
            String validJson = mapper.writeValueAsString(validDto);
            System.out.println("Valid DTO serialized successfully:\n" + validJson);
        } catch (JsonGenerationException e) {
            System.err.println("Error serializing valid DTO: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Unexpected error: " + e.getMessage());
        }

        System.out.println("\n---");

        // 示例2：无效对象 - 序列化失败
        // field1被设置为null，这将触发自定义序列化器的校验
        BigJsonDto invalidDto = BigJsonDto.builder()
            .field1(null) // 必填字段为null
            .field2("Bob")
            .field3("Carol")
            .fieldN("N")
            .build();

        try {
            System.out.println("Attempting to serialize invalid DTO...");
            String resultingJson = mapper.writeValueAsString(invalidDto); // <- 此行会抛出JsonGenerationException
            System.out.println("Invalid DTO serialized successfully (should not happen):\n" + resultingJson);
        } catch (JsonGenerationException e) {
            System.err.println("Successfully caught expected serialization error for invalid DTO: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Unexpected error when serializing invalid DTO: " + e.getMessage());
        }
    }
}

运行结果示例：

Valid DTO serialized successfully:
{"field1":"value1","field2":"value2","field3":"value3"}

---
Attempting to serialize invalid DTO...
Successfully caught expected serialization error for invalid DTO: BigJsonDto instance is not valid: required fields are null

4. 总结与注意事项

通过自定义Jackson序列化器，我们能够精确控制POJO到JSON的转换过程，并在序列化阶段实现严格的必填字段空值校验。这种方法提供了比Jackson内置注解更强大的控制力，确保了输出JSON数据的完整性和有效性。

关键点回顾：

• JsonSerializer：继承此类并重写serialize()方法是实现自定义序列化逻辑的核心。
• JsonGenerationException：在serialize()方法中，通过抛出此异常来中断序列化过程。
• 手动写入字段：如果验证通过，必须在serialize()方法中手动使用JsonGenerator写入所有JSON字段。
• 注册方式：可以选择使用@JsonSerialize注解（针对特定类）或通过SimpleModule进行全局注册。全局注册时，handledType()方法是必需的。
• 性能考量：对于非常大的对象或高并发场景，手动写入字段可能会带来一定的性能开销。如果性能是关键瓶颈，需要仔细评估。
• 错误处理：在调用mapper.writeValueAsString()时，务必捕获可能抛出的JsonGenerationException或其他IOException，以便妥善处理序列化失败的情况。

这种自定义序列化器的模式不仅限于空值校验，还可以用于实现更复杂的业务逻辑，例如数据脱敏、格式转换或根据特定条件动态调整输出内容。