【Java入門】Jacksonの@JsonViewアノテーションでJSON出力を動的に制御する方法

JavaでJSONを扱う際、状況に応じて出力するフィールドを切り替えたいケースは多くあります。例えば、外部向けのAPIでは公開可能な情報だけを返し、内部向けの処理では詳細な情報まで含めたいといった場面です。そんなときに役立つのが、Jacksonライブラリが提供する@JsonViewアノテーションです。

@JsonViewアノテーションとは

@JsonViewアノテーションを使用すると、シリアライズ（Javaオブジェクト→JSON）およびデシリアライズ（JSON→Javaオブジェクト）の過程において、プロパティを動的に含めたり除外したりすることができます。

実際にJSONを出力する際は、ObjectMapperクラスのwriterWithView()メソッドを使って、どのビューを適用するかを指定します。これにより、同じJavaオブジェクトからでも、用途に応じて異なる形式のJSONを生成できるようになります。

構文

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

@JsonViewは、アノテーション型・メソッド・フィールドに対して付与でき、実行時（RUNTIME）に情報が保持される仕組みになっています。

使用例

以下のサンプルコードでは、「Public」と「Internal」という2つのビューを定義し、ビューごとに出力されるフィールドがどう変わるかを確認できます。

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonView;
import com.fasterxml.jackson.core.JsonProcessingException;

public class JsonViewAnnotationTest {
    public static void main(String args[]) throws JsonProcessingException {
        ObjectMapper objectMapper = new ObjectMapper();
        // Publicビューを適用してJSONを生成
        String jsonString = objectMapper.writerWithView(Views.Public.class).writeValueAsString(new Person());
        // Internalビューを適用してJSONを生成
        String jsonStringInternal = objectMapper.writerWithView(Views.Internal.class).writeValueAsString(new Person());
        System.out.println(jsonString);
        System.out.println(jsonStringInternal);
    }
}

// Personクラス
class Person {
    @JsonView(Views.Public.class)
    public long personId = 115;

    @JsonView(Views.Public.class)
    public String personName = "Raja Ramesh";

    @JsonView(Views.Internal.class)
    public String gender = "male";

    @Override
    public String toString() {
        return "Person{" +
                "personId=" + personId +
                ", personName='" + personName + '\'' +
                ", gender='" + gender + '\'' +
                '}';
    }
}

// ビューの定義
class Views {
    static class Public {}
    static class Internal extends Public {}
}

ポイント解説

• Views.Public：基本となる公開用ビュー。personIdとpersonNameが対象。
• Views.Internal：Publicを継承した内部用ビュー。Publicのフィールドに加えてgenderも含まれる。
• ビューを継承関係にすることで、「基本の項目＋追加の項目」という階層的な制御が簡単に実現できます。

実行結果

{"personId":115,"personName":"Raja Ramesh"}
{"personId":115,"personName":"Raja Ramesh","gender":"male"}

1行目はPublicビューを適用した結果で、personIdとpersonNameのみが出力されています。一方、2行目はInternalビューを適用した結果で、genderフィールドも含めて出力されていることがわかります。

まとめ

@JsonViewアノテーションを使えば、1つのクラス定義から複数の粒度のJSONを柔軟に生成できます。REST APIで「一覧表示用」「詳細表示用」などレスポンスの内容を使い分けたい場合や、機密性の高いフィールドを特定の条件下でのみ出力したい場合に非常に有効な手法です。Spring Frameworkと組み合わせれば、コントローラ単位でも簡単にビューを指定できるため、実務でも広く活用されています。