Javaの@JsonFilterアノテーションとは？カスタムフィルタでJSON出力を制御する方法

@JsonFilterアノテーションは、JavaオブジェクトをJSONにシリアライズする際にカスタムフィルタを定義するためのアノテーションです。Jacksonライブラリが提供する機能の一つで、特定のプロパティだけを出力したり、逆に不要なプロパティを除外したりすることができます。

実際にフィルタを適用するには、FilterProviderクラスを使ってフィルタを定義し、フィルタの実インスタンスを取得する必要があります。その後、このFilterProviderをObjectMapperクラスに設定することで、シリアライズ時のフィルタリングが有効になります。

構文

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

このアノテーションは、クラスやメソッド、フィールド、パラメータなどに対して付与でき、実行時（RUNTIME）に有効になります。引数にはフィルタを識別するための文字列（フィルタ名）を指定します。

コード例

以下の例では、@JsonFilter("customFilter")のように引数として「customFilter」を宣言しています。これにより、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：フィルタ名とフィルタの実体を紐付けるプロバイダです。addFilter()メソッドで登録します。
• mapper.writer(filterProvider)：通常のwriteValueAsString()ではなく、FilterProviderを渡したwriter経由でシリアライズすることで、フィルタが適用されます。

このように@JsonFilterを使うことで、同じBeanクラスでも状況に応じて出力する項目を柔軟に切り替えられます。例えば、一般ユーザー向けAPIでは個人情報を隠し、管理者向けAPIでは全項目を返すといった制御が、1つのクラスで実現可能になります。セキュリティやレスポンスサイズの最適化が必要な場面で非常に有用なアノテーションです。