Java에서 @JsonFilter 어노테이션 완벽 가이드: 직렬화 필터링 방법

Java에서 @JsonFilter 어노테이션은 객체를 JSON으로 직렬화할 때 커스텀 필터(custom filter)를 정의하기 위해 사용됩니다. 이 어노테이션을 활용하면 특정 상황에 따라 노출할 속성과 숨길 속성을 유연하게 제어할 수 있어, 민감한 데이터를 외부로 전송하지 않거나 API 응답을 동적으로 조정해야 할 때 매우 유용합니다.

@JsonFilter를 사용하려면 FilterProvider 클래스로 필터를 정의하고 실제 필터 인스턴스를 얻은 뒤, 이를 ObjectMapper 클래스에 설정해야 합니다.

문법(Syntax)

@Target(value={ANNOTATION_TYPE,TYPE,METHOD,FIELD,PARAMETER})
@Retention(value=RUNTIME)
public @interface JsonFilter

동작 원리

@JsonFilter는 클래스, 메서드, 필드, 파라미터 등 다양한 대상에 적용할 수 있으며, 런타임 시점에 필터가 적용됩니다. 아래 예제에서는 customFilter라는 이름의 필터를 @JsonFilter 어노테이션의 인자로 선언하여, 빈(Bean) 객체의 empName 속성만 추출하고 나머지 속성들은 모두 필터링하여 제외합니다.

예제 코드

import com.fasterxml.jackson.annotation.JsonFilter;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ser.FilterProvider;
import com.fasterxml.jackson.databind.ser.impl.SimpleBeanPropertyFilter;
import com.fasterxml.jackson.databind.ser.impl.SimpleFilterProvider;

public class JsonFilterAnnotationTest {
   public static void main(String args[]) throws JsonProcessingException {
      ObjectMapper mapper = new ObjectMapper();
      FilterProvider filterProvider = new SimpleFilterProvider()
            .addFilter("customFilter",
                  SimpleBeanPropertyFilter.filterOutAllExcept("empName"));
      String jsonString = mapper.writer(filterProvider)
            .writeValueAsString(new FilterBean());
      System.out.println(jsonString);
   }
}

@JsonFilter("customFilter")
class FilterBean {
   public int empId = 110;
   public String empName = "Raja Ramesh";
   public String gender = "male";
}

실행 결과

{"empName":"Raja Ramesh"}

핵심 포인트 정리

• SimpleBeanPropertyFilter.filterOutAllExcept(): 지정한 속성만 남기고 나머지는 모두 제외합니다.
• serializeAllExcept(): 반대로 지정한 속성만 제외하고 나머지는 모두 직렬화합니다.
• SimpleFilterProvider: 필터 ID와 실제 필터 구현체를 연결하는 역할을 합니다.
• 필터를 설정했지만 해당 ID의 필터가 제공되지 않으면 직렬화 시점에 예외가 발생하므로 주의해야 합니다.

이처럼 @JsonFilter를 활용하면 하나의 객체라도 요청 조건이나 사용자 권한에 따라 서로 다른 형태의 JSON 응답을 만들 수 있어, REST API 설계에서 데이터 노출 범위를 세밀하게 관리하는 데 큰 도움이 됩니다.