Java Gson FieldNamingPolicy 열거형으로 JSON 필드 이름 규칙 지정하기

Gson 라이브러리는 FieldNamingPolicy 열거형(enum)을 통해 다양한 필드 명명 규칙(naming convention)을 제공합니다. GsonBuilder 클래스의 setFieldNamingPolicy() 메서드를 사용하면 객체를 JSON으로 직렬화할 때 필드 이름을 원하는 형식으로 손쉽게 변환할 수 있습니다.

FieldNamingPolicy 열거형 상수

• IDENTITY — 이 정책을 적용하면 필드 이름이 원본 그대로 유지됩니다.
• LOWER_CASE_WITH_DASHES — Java 필드 이름을 카멜 케이스(camel case)에서 각 단어가 대시(-)로 구분되는 소문자 형식으로 변경합니다.
• LOWER_CASE_WITH_UNDERSCORES — Java 필드 이름을 카멜 케이스에서 각 단어가 밑줄(_)로 구분되는 소문자 형식으로 변경합니다.
• UPPER_CAMEL_CASE — JSON으로 직렬화할 때 Java 필드 이름의 첫 글자가 대문자로 표시되도록 보장합니다.
• UPPER_CAMEL_CASE_WITH_SPACES — JSON으로 직렬화할 때 첫 글자를 대문자로 표시하고, 단어 사이를 공백으로 구분합니다.

구문

public enum FieldNamingPolicy extends Enum<FieldNamingPolicy> implements FieldNamingStrategy

예제

아래 예제에서는 하나의 Employee 객체를 서로 다른 명명 정책으로 직렬화하여 결과를 비교합니다.

import com.google.gson.FieldNamingPolicy;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class GsonFieldNamingPolicyTest {
    public static void main(String[] args) {
        Employee emp = new Employee();
        emp.setEmpId(115);
        emp.setFirstName("Raja");
        emp.setLastName("Ramesh");

        GsonBuilder gsonBuilder = new GsonBuilder();

        Gson gson1 = gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_DASHES).create();
        System.out.println("LOWER_CASE_WITH_DASHES: " + gson1.toJson(emp));

        Gson gson2 = gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES).create();
        System.out.println("LOWER_CASE_WITH_UNDERSCORES: " + gson2.toJson(emp));

        Gson gson3 = gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE).create();
        System.out.println("UPPER_CAMEL_CASE: " + gson3.toJson(emp));

        Gson gson4 = gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE_WITH_SPACES).create();
        System.out.println("UPPER_CAMEL_CASE_WITH_SPACES: " + gson4.toJson(emp));

        Gson gson5 = gsonBuilder.setFieldNamingPolicy(FieldNamingPolicy.IDENTITY).create();
        System.out.println("IDENTITY: " + gson5.toJson(emp));
    }
}

// Employee 클래스
class Employee {
    private int empId;
    private String firstName;
    private String lastName;

    public int getEmpId() {
        return empId;
    }
    public void setEmpId(int empId) {
        this.empId = empId;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}

실행 결과

각 명명 정책에 따라 동일한 객체가 아래와 같이 다른 JSON 키 이름으로 변환되는 것을 확인할 수 있습니다.

LOWER_CASE_WITH_DASHES: {"emp-id":115,"first-name":"Raja","last-name":"Ramesh"}
LOWER_CASE_WITH_UNDERSCORES: {"emp_id":115,"first_name":"Raja","last_name":"Ramesh"}
UPPER_CAMEL_CASE: {"EmpId":115,"FirstName":"Raja","LastName":"Ramesh"}
UPPER_CAMEL_CASE_WITH_SPACES: {"Emp Id":115,"First Name":"Raja","Last Name":"Ramesh"}
IDENTITY: {"empId":115,"firstName":"Raja","lastName":"Ramesh"}

정리

API 설계 시 외부 시스템이 요구하는 JSON 키 형식(예: snake_case, kebab-case)이 있다면 FieldNamingPolicy를 활용하면 별도의 어노테이션 없이 전역적으로 일관된 명명 규칙을 적용할 수 있습니다. 특정 필드만 다르게 처리해야 하는 경우에는 @SerializedName 어노테이션을 함께 사용하는 것이 좋습니다.