B컷전문 | 개발과 인생의 이야기

Spring Boot에서 Jackson으로 Java 객체를 JSON으로 변환할 때 사용하는 필수 어노테이션 @JsonProperty, @JsonIgnore, @JsonInclude의 실제 사용법과 예제를 소개합니다.

---

Spring Boot 환경에서는 컨트롤러에서 반환하는 객체가 자동으로 JSON으로 변환됩니다. 이 변환 과정은 내부적으로 Jackson의 ObjectMapper가 담당하며, 우리가 원하는 형태로 JSON 구조를 변경할 수 있도록 다양한 어노테이션을 제공합니다.

이번 글에서는 가장 실무에서 많이 쓰이는 직렬화 제어 어노테이션에 대해 알아보고, 예제와 함께 활용법을 정리합니다.

---

1. @JsonProperty – JSON 필드명 변경

기본적으로 Java의 camelCase 필드는 JSON에서는 동일한 이름으로 변환됩니다. 그러나 특정 필드를 snake_case로 보내야 하는 경우 @JsonProperty를 활용할 수 있습니다.

public class User {

    @JsonProperty("user_name")
    private String userName;

    private int age;

    // 생성자, getter, setter 생략
}

결과

{
  "user_name": "홍길동",
  "age": 30
}

특히 외부 API와 통신할 때 필드명을 맞춰야 할 경우 매우 유용합니다.

---

2. @JsonIgnore – 특정 필드를 직렬화에서 제외

보안 정보나 클라이언트에 노출되면 안 되는 데이터를 제외할 때 사용합니다.

public class User {

    private String userName;
    private int age;

    @JsonIgnore
    private String password;

    // 생성자, getter, setter 생략
}

결과

{
  "userName": "홍길동",
  "age": 30
}

password 필드는 직렬화 시 포함되지 않습니다.

---

3. @JsonInclude – null, 빈 값 필드 제외

불필요한 null 값을 포함시키지 않으려면 @JsonInclude를 사용할 수 있습니다.

@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {

    private String userName;
    private Integer age;
    private String email;

    // 생성자, getter, setter 생략
}

사용 예

User user = new User("홍길동", 30, null);
String json = objectMapper.writeValueAsString(user);

결과

{
  "userName": "홍길동",
  "age": 30
}

email 필드는 null이므로 제외됩니다.

전역으로 설정하고 싶다면 application.yml에서 default-property-inclusion: non_null을 설정할 수도 있습니다.

---

4. 기타 유용한 직렬화 어노테이션

어노테이션 설명

@JsonFormat	날짜 및 시간 포맷 지정
@JsonUnwrapped	Nested Object의 필드를 부모 객체로 풀어줌
@JsonAlias	역직렬화 시 여러 이름을 허용

@JsonFormat 예시

public class User {
    private String userName;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createdAt;

    // 생성자, getter, setter 생략
}

결과

{
  "userName": "홍길동",
  "createdAt": "2025-05-09 14:00:00"
}

날짜 포맷은 글로벌 설정보다 클래스에 지정한 포맷이 우선 적용됩니다.

---

5. 실전: Spring Boot 컨트롤러 예시

@RestController
public class UserController {

    @GetMapping("/user")
    public User getUser() {
        User user = new User();
        user.setUserName("홍길동");
        user.setAge(30);
        user.setPassword("secret");  // @JsonIgnore로 제외됨
        user.setEmail(null);         // @JsonInclude로 제외됨
        return user;
    }
}

결과

{
  "userName": "홍길동",
  "age": 30
}

---

결론 및 팁 요약

• @JsonProperty: JSON 필드명 변경
• @JsonIgnore: 특정 필드 직렬화 제외
• @JsonInclude: null 또는 빈 값 제외
• 이 어노테이션을 조합하면 불필요한 DTO를 만들 필요 없이 객체 직렬화 포맷을 깔끔하게 관리할 수 있습니다.

---

다음 회차 예고

4화에서는 JSON을 Java 객체로 역직렬화할 때 발생할 수 있는 문제와 해결법을 알아봅니다. 특히 LocalDate, Enum, Optional과 같이 기본 타입이 아닌 필드에 대한 역직렬화 대응법을 실전 예제로 다룹니다.