0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【Spring Boot 4】Jackson 3移行ガイド:既定値の変更でAPIの出力が変わる

0
Posted at

はじめに

Spring Boot 4では、JSON処理のライブラリがJackson 2からJackson 3に変わりました。パッケージ名が変わるだけでなく、既定値もいくつか変わっているため、バージョンを上げるとAPIのレスポンスやテストの結果が変わることがあります。

この記事では、Jackson 3の変更点と、Spring Bootのアプリで実際に影響が出るところ、移行の進め方を整理します。

  • 対象読者:Spring Boot 3から4に移行する方、JSONのテストが落ちて困っている方
  • 前提バージョン:Spring Boot 4.0 / Java 25
  • この記事で分かること:Jackson 3の主な変更点、Spring Bootで影響が出る既定値の変更、テストの直し方、段階的な移行の手順

結論

  • Jackson 3は、パッケージが tools.jackson に変わり、マッパーが不変の JsonMapper に、例外が非検査例外になった。DTOに付けるアノテーションはそのまま使える
  • Spring Bootで特に影響が出やすいのは「JSONの項目がアルファベット順になる」「基本型へのnullがエラーになる」「enumの変換に toString() が使われる」の3つ
  • すぐに対応できない場合は spring.jackson.use-jackson2-defaults=true で、Spring Boot 3に近い動きのまま移行できる

Jackson 3の主な変更点

変更 Jackson 2 Jackson 3
必要なJava Java 8以上 Java 17以上
パッケージ com.fasterxml.jackson tools.jackson(アノテーションは除く)
マッパー 後から設定を変えられる ObjectMapper 作成後は変わらない JsonMapper
例外 検査例外 JsonProcessingException 非検査例外 JacksonException
日付・時刻型 JavaTimeModule の追加が必要 本体に組み込み済み

マッパーが不変になった

// Jackson 3:Builderで作り、作ったあとは変わらない
JsonMapper mapper = JsonMapper.builder()
        .enable(SerializationFeature.INDENT_OUTPUT)
        .build();

// 少しだけ違う設定が欲しいときは、元を変えずに新しいものを作る
JsonMapper compact = mapper.rebuild()
        .disable(SerializationFeature.INDENT_OUTPUT)
        .build();

作成後に設定を変えられないので、複数のスレッドから安全に使えます。共有しているマッパーの設定を、どこかのコードが書き換えてしまう事故も起きません。

例外が非検査例外になった

// Jackson 2:ラムダの中では try-catch が必要だった
List<String> jsons = orders.stream()
        .map(o -> {
            try {
                return objectMapper.writeValueAsString(o);
            } catch (JsonProcessingException e) {
                throw new UncheckedIOException(e);
            }
        })
        .toList();

// Jackson 3:そのまま書ける
List<String> jsons = orders.stream()
        .map(jsonMapper::writeValueAsString)
        .toList();

アノテーションはそのまま使える

@JsonProperty、@JsonIgnore、@JsonFormat などのアノテーションは、Jackson 3でも com.fasterxml.jackson.annotation パッケージのままです。DTOの書き換えは、ほとんど必要ありません。書き換えが必要なのは、主にマッパーを直接使っているコードです。

Spring Bootで影響が出る既定値の変更

Jackson 3では多くの既定値が変わりましたが、その一部は、Spring Boot 3がすでに同じ設定にしていました。例えば、Spring Boot 3の自動設定のマッパーは、日付をISO-8601の文字列で出力し、知らない項目が来てもエラーにしない設定になっていました。

そのため、Spring Bootの自動設定のマッパーを使っているアプリでは、次の表の「影響」の列で見るのが正確です。

設定 Jackson 3の既定 Spring Boot 3での動き 影響
項目をアルファベット順に並べる 有効 宣言順 あり
基本型へのnullをエラーにする 有効 0などになる あり
enumの変換に toString() を使う 有効 name() を使う toString() を上書きしていればあり
JSONの後ろの余計な文字をエラーにする 有効 エラーにしない あり(不正な入力のみ)
日付を数値で出力する 無効 すでに無効 なし
知らない項目をエラーにする 無効 すでに無効 なし

ただし、new ObjectMapper() のように自分でマッパーを作っていたコードは、Spring Bootの設定が効いていなかったので、日付の出力なども変わります。

項目の順番

テストで最も問題になりやすい変更です。JSONを文字列のまま比べているテストは、項目の順番が変わると失敗します。

// 項目の順番に依存するので、失敗しやすい
assertThat(json).isEqualTo("{\"name\":\"Tシャツ\",\"id\":1}");

項目ごとに比べる書き方に直すと、順番に左右されなくなります。

// MockMvcTester(Spring 6.2以降)で項目ごとに確認する
assertThat(mvc.get().uri("/api/products/1"))
        .hasStatusOk()
        .bodyJson()
        .extractingPath("$.name").isEqualTo("Tシャツ");

基本型へのnull

int や long などの基本型のフィールドにnullが来ると、Jackson 2では0などの初期値になっていましたが、Jackson 3ではエラーになります。

public record OrderRequest(long productId, int quantity) {}
{"productId": 1, "quantity": null}

このリクエストは、Jackson 3では変換エラー(400 Bad Request)になります。nullを受け付けたいなら Integer などのラッパー型にし、受け付けたくないならそのままにしておけば、不正な入力を早めに弾けます。

enumの変換

enumで toString() を上書きしている場合、JSONの出力と入力に、その戻り値が使われるようになります。

public enum OrderStatus {
    PAID;

    @Override
    public String toString() {
        return "支払済み";   // Jackson 3ではこの値がJSONに出る
    }
}

画面表示用に toString() を上書きしているenumは、JSONの値が変わってしまうので注意が必要です。JSONの値を固定したいなら、@JsonValue を付けたメソッドで明示します。

Spring Boot側の変更

Spring Boot 3 Spring Boot 4
Jackson2ObjectMapperBuilderCustomizer JsonMapperBuilderCustomizer
@JsonComponent @JacksonComponent
@JsonMixin @JacksonMixin
spring.jackson.read.* spring.jackson.json.read.*
spring.jackson.write.* spring.jackson.json.write.*

マッパーの設定を変えるときは、JsonMapperBuilderCustomizer を使います。

@Bean
JsonMapperBuilderCustomizer jsonCustomizer() {
    return builder -> builder
            .enable(SerializationFeature.INDENT_OUTPUT);
}

注意点が2つあります。

  • 自分で ObjectMapper のBeanを定義しても、Spring Boot 4では効きません。自動設定のマッパーを置き換えたいときは、JsonMapper のBeanを定義します
  • クラスパスにあるJacksonのモジュールは、すべて自動で登録されるようになりました。止めたいときは spring.jackson.find-and-add-modules=false を設定します

移行の進め方

Springチームは、次の順で検討することを勧めています。

  1. Jackson 3に移行する(既定値もJackson 3にする)
  2. spring.jackson.use-jackson2-defaults を設定して、Jackson 3に移行する
  3. 一時的にJackson 2を使い続け、あとでJackson 3に移行する

すぐにテストやAPIの利用者への影響を確認できない場合は、2から始めて段階的に進めるのが安全です。

spring:
  jackson:
    use-jackson2-defaults: true   # Spring Boot 3のJackson 2に近い既定値で動かす

この設定で動かしながら、JSONを比べるテストを項目ごとの比較に直し、最後に設定を外してJackson 3の既定値に切り替えます。

どうしてもJackson 2が必要なライブラリがある場合は、非推奨の spring-boot-jackson2 モジュールで、Jackson 2を一時的に使い続けることもできます。設定は spring.jackson2.* で行います。ただし、Jackson 2の自動設定は将来削除される予定なので、あくまで一時的な手段です。

まとめ

  • Jackson 3では、パッケージ、マッパー(不変の JsonMapper)、例外(非検査例外)が変わった。アノテーションはそのまま使える
  • Spring Bootの自動設定のマッパーでは、日付の形式と知らない項目の扱いは変わらない
  • 影響が出やすいのは、項目の順番、基本型へのnull、enumの toString() の3つ
  • JSONを文字列で比べるテストは、項目ごとの比較に直す
  • 設定の変更は JsonMapperBuilderCustomizer で行う。ObjectMapper のBeanは効かない
  • すぐに対応できなければ spring.jackson.use-jackson2-defaults=true で段階的に移行する

関連記事

Jackson 3の変更は、テストが落ちて初めて気づくことが多いものです。移行前に、自分のアプリで影響が出る箇所を確認しておくと安心です。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?