はじめに
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チームは、次の順で検討することを勧めています。
- Jackson 3に移行する(既定値もJackson 3にする)
-
spring.jackson.use-jackson2-defaultsを設定して、Jackson 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で段階的に移行する
関連記事
- Spring Boot 3と4は何が違うのか:比較表で押さえる世代の変化
- Spring Boot 3.5から4.0への移行:破壊的変更とチェックリスト
- RestClient / WebClientのタイムアウトとコネクションプール:既定値のままでは本番に出せない
Jackson 3の変更は、テストが落ちて初めて気づくことが多いものです。移行前に、自分のアプリで影響が出る箇所を確認しておくと安心です。