JavaのJacksonで使える@JsonUnwrappedアノテーションの重要性と使い方を解説

@JsonUnwrappedアノテーションは、Jacksonによるシリアライズ（Javaオブジェクト→JSON）およびデシリアライズ（JSON→Javaオブジェクト）の処理の中で、ネストされたオブジェクトの値を「展開（アンラップ）」するために使用されます。このアノテーションを付与することで、構成クラス（コンポジションで保持しているクラス）のフィールド値を、あたかも親クラス自身のプロパティであるかのように扱えます。

例えば、EmployeeクラスがAddressクラスを保持している場合、通常であれば「address」というキーの下にネストしたJSONが出力されますが、@JsonUnwrappedを使うとAddressの各フィールドがフラットな形で親の直下に並びます。

構文

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

使用例

import com.fasterxml.jackson.annotation.JsonUnwrapped;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;

public class JsonUnwrappedAnnotationTest {
    public static void main(String args[]) throws JsonProcessingException {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(new Employee());
        System.out.println(jsonString);
    }
}

class Employee {
    public int empId = 110;
    public String empName = "Raja Ramesh";

    @JsonUnwrapped
    public Address address = new Address();

    // Addressクラス
    public static class Address {
        public String doorNumber = "1118";
        public String street = "madhapur";
        public String pinCode = "500081";
        public String city = "Hyderabad";
    }
}

実行結果

{
    "empId" : 110,
    "empName" : "Raja Ramesh",
    "doorNumber" : "1118",
    "street" : "madhapur",
    "pinCode" : "500081",
    "city" : "Hyderabad"
}

このように、Addressオブジェクトの各フィールド（doorNumber、street、pinCode、city）が「address」というキーで囲まれることなく、Employeeのプロパティとして直接出力されているのが分かります。

prefix / suffix属性で名前の衝突を避ける

@JsonUnwrappedにはprefixとsuffix属性が用意されており、展開後のプロパティ名に接頭辞や接尾辞を追加できます。親クラスと子クラスに同名のフィールドが存在する場合などの名前の衝突を回避したいときに便利です。

@JsonUnwrapped(prefix = "addr.")
public Address address = new Address();

上記のように指定すると、出力されるキーは「addr.doorNumber」「addr.street」のようになります。

主な注意点

• @JsonUnwrappedは、フィールド、ゲッター／セッターメソッド、コンストラクタの引数に対して指定できます。
• java.util.Map型のプロパティには適用できません。
• デシリアライズ時にも同様に機能し、フラットなJSONからネストされたオブジェクトへ値を正しくマッピングできます。