Java Gson으로 null 필드 직렬화하기 – serializeNulls() 메서드 활용 가이드

기본적으로 Gson 객체는 null 값을 가진 필드를 JSON으로 직렬화하지 않습니다. 즉, Java 객체의 특정 필드가 null이면 Gson은 해당 필드를 출력 결과에서 자동으로 제외합니다. 하지만 실무에서는 API 응답 등에서 null 필드도 명시적으로 표현해야 하는 경우가 종종 있습니다.

이럴 때 GsonBuilder 클래스를 사용하면 Gson이 null 값을 직렬화하도록 강제할 수 있습니다. 핵심은 Gson 객체를 생성하기 전에 GsonBuilder 인스턴스에서 serializeNulls() 메서드를 호출하는 것입니다. 이 메서드가 호출된 후 GsonBuilder로 생성된 Gson 인스턴스는 직렬화된 JSON에 null 필드를 포함하게 됩니다.

문법(Syntax)

public GsonBuilder serializeNulls()

예제 코드

아래 예제에서는 Employee 객체의 name 필드를 null로 설정한 뒤, serializeNulls()를 적용한 Gson으로 직렬화합니다.

import com.google.gson.*;
import com.google.gson.annotations.*;

public class NullFieldTest {
    public static void main(String args[]) {
        GsonBuilder builder = new GsonBuilder();
        builder.serializeNulls(); // null 값 직렬화 활성화
        Gson gson = builder.setPrettyPrinting().create();

        Employee emp = new Employee(null, 25, 40000.00);
        String jsonEmp = gson.toJson(emp);
        System.out.println(jsonEmp);
    }
}

// Employee 클래스
class Employee {
    @Since(1.0)
    public String name;

    @Since(1.0)
    public int age;

    @Since(2.0)
    public double salary;

    public Employee(String name, int age, double salary) {
        this.name = name;
        this.age = age;
        this.salary = salary;
    }
}

실행 결과(Output)

{
    "name": null,
    "age": 25,
    "salary": 40000.0
}

정리

위 실행 결과에서 볼 수 있듯이, serializeNulls()를 호출하면 name 필드의 null 값이 JSON에 그대로 포함됩니다. 만약 이 설정 없이 직렬화했다면 "name" 키 자체가 결과 JSON에서 생략되었을 것입니다. 참고로 예제에 사용된 @Since 어노테이션은 버전 관리를 위해 필드가 도입된 버전을 표시하는 용도로, setVersion()과 함께 사용하면 특정 버전 이상의 필드만 직렬화 대상에 포함할 수 있습니다.