--- title: "JacksonをMavenで導入する手順｜2.22と3.2の依存の違いとObjectMapper・JsonNodeの使い方" url: "https://www.issoh.co.jp/tech/details/3825/" published: 2024-10-11 updated: 2026-09-27 categories: ["Java"] publisher: "株式会社一創" --- # JacksonをMavenで導入する手順｜2.22と3.2の依存の違いとObjectMapper・JsonNodeの使い方 JacksonはJavaでJSONを読み書きするライブラリです。Mavenなら`pom.xml`に`jackson-databind`を1つ書けば、残りの部品は自動で入ります。ただし2025年10月に3.0が出て以降、Jacksonは座標もパッケージ名も違う2系と3系が並行して更新されています。どちらを書くかで`import`文も既定の挙動も変わります。この記事では、2.22.3と3.2.3の依存の書き方、Java 25で実行して確かめた既定動作の違い、ObjectMapperとJsonNodeを使ったJSONの変換・参照・編集を、実行結果付きで説明します。 ## まとめ：JacksonをMavenで使うときの要点 - **書く依存は1つ**：`jackson-databind`を追加すれば、`jackson-core`と`jackson-annotations`は推移的依存で入る。 - **2系と3系は座標が違う**：2系は`com.fasterxml.jackson.core`（2026年9月時点の最新2.22.3）、3系は`tools.jackson.core`（同3.2.3）。3系でも`jackson-annotations`だけは2系の座標のまま使う。 - **選び方**：Java 17以上の新規開発とSpring Boot 4系は3系。Java 8・11が残る環境やSpring Boot 3系は2系。長く据え置くならLTSの2.21系・3.1系が候補になる。 - **3系は既定動作が変わった**：未知のプロパティを無視し、`java.time`を標準で扱い、例外は非検査例外になる。2系のコードをパッケージ名だけ置き換えても同じ結果にはならない。 - **JSONの扱い方は2通り**：型が決まっているならObjectMapperでrecordやクラスへ変換し、構造が不定ならJsonNodeのツリーで辿る。 以下、依存の書き方、2系と3系の違い、ObjectMapper、JsonNodeの参照と編集、失敗しやすい点の順に説明します。 ## Jacksonを構成する3つのモジュールと役割 Jacksonは用途ごとにjarが分かれています。普段コードから直接使うのは`jackson-databind`の`ObjectMapper`と`JsonNode`で、残りの2つはその土台です。 | artifactId | 役割 | 主なクラス | | ------------------- | ------------------------ | ------------------------- | | jackson-core | JSONを1トークンずつ読み書きする低水準API | JsonParser、JsonGenerator | | jackson-annotations | 変換規則を指定するアノテーション | @JsonProperty、@JsonIgnore | | jackson-databind | JavaオブジェクトやツリーとJSONの変換 | ObjectMapper、JsonNode | databindはcoreとannotationsに依存しているため、databindだけを書けば3つが揃います。`mvn dependency:tree`で確かめた結果が次です。annotationsの版がパッチ番号の無い`2.22`になっているのは、2.20以降annotationsだけが「2.20」「2.21」のようにマイナー版単位で出る方式に変わったためです。 ``` demo:j2:jar:1 \- com.fasterxml.jackson.core:jackson-databind:jar:2.22.3:compile +- com.fasterxml.jackson.core:jackson-annotations:jar:2.22:compile \- com.fasterxml.jackson.core:jackson-core:jar:2.22.3:compile ``` 2系の日付・時刻対応（jackson-datatype-jsr310）と、2系・3系のYAML・CSV対応（jackson-dataformat-\*）は別モジュールです。3系のjava.time対応はdatabindに組み込まれています。必要になった時点で追加し、版はBOMで揃えます（後述）。 ## pom.xmlへの追加：2系と3系の依存の書き方 ### Jackson 2系のMaven座標と対応Java 既存プロジェクトの大半が使っている系統です。`jackson-databind` 2.22.3はJava 8向けにコンパイルされているので、古いJDKが残る環境でも使えます。 ``` com.fasterxml.jackson.core jackson-databind 2.22.3 ``` パッケージは`com.fasterxml.jackson.databind`です。検索でよく見かける`com.fasterxml.jackson.databind.JsonNode`はこの系統のクラス名です。 ### Jackson 3系のMaven座標とannotationsの扱い 3系はgroupIdとJavaパッケージがどちらも`tools.jackson`に変わりました。3.2.3のpomはJava 17を対象にしています。 ``` tools.jackson.core jackson-databind 3.2.3 ``` このときの依存ツリーでは、annotationsだけが2系の座標で入ります。 ``` demo:j3:jar:1 \- tools.jackson.core:jackson-databind:jar:3.2.3:compile +- com.fasterxml.jackson.core:jackson-annotations:jar:2.22:compile \- tools.jackson.core:jackson-core:jar:3.2.3:compile ``` databind 3.2.3のpomにも「Annotations remain at Jackson 2.x group id」とコメントがあり、`@JsonProperty`などは2系と3系で同じクラスを共有します。注意したいのは、Maven Centralの`jackson-annotations`の`maven-metadata.xml`では、2026年9月27日に取得した時点で``も``も`3.0-rc5`を指していることです。これは正式版ではないRC（リリース候補）なので、「最新」を機械的に拾うツールやスクリプトで版を決めると誤ります。annotationsの版はdatabindの推移的依存かBOMに任せます。アノテーションを直接使う場合は、BOMで版を管理したうえでannotationsを明示的な依存として宣言する方法もあります。 ### jackson-bomによる関連モジュールのバージョン管理 databindに加えて`jackson-datatype-jsr310`などを入れる場合は、`jackson-bom`を`dependencyManagement`でimportします。各依存から``を省き、BOMの管理する組み合わせに揃えられます。ただし、個別の版指定や別のdependencyManagement設定で上書きしていないかは確認が必要です。 ``` com.fasterxml.jackson jackson-bom 2.22.3 pom import com.fasterxml.jackson.core jackson-databind com.fasterxml.jackson.datatype jackson-datatype-jsr310 ``` 3系のBOMは`tools.jackson:jackson-bom`です。Spring Bootを使っている場合はBootがJacksonの版を管理しているので、BOMも``も書かずに済みます。 ### Gradleで追加する書き方 Gradle（Kotlin DSL）では座標を1行で書きます。BOMは`platform()`で読み込みます。 ``` dependencies { implementation(platform("com.fasterxml.jackson:jackson-bom:2.22.3")) implementation("com.fasterxml.jackson.core:jackson-databind") // 3系の場合 // implementation("tools.jackson.core:jackson-databind:3.2.3") } ``` ## Jackson 2.22と3.2の違い：既定動作を実測した対照表 3系への移行はパッケージ名の置換だけでは終わりません。同じJSONと、比較項目に応じたrecord・Beanを2.22.3と3.2.3に渡し、Temurin 25で実行した結果を並べます。 | 項目 | 2.22.3 | 3.2.3 | | ------------------ | ----------------------------- | ------------------------ | | groupId／パッケージ | com.fasterxml.jackson | tools.jackson | | 対象Java（databind） | 8 | 17 | | 例外の種類 | 検査例外（IOException系） | 非検査例外（RuntimeException系） | | recordに無い項目を含むJSON | UnrecognizedPropertyException | 無視して変換 | | intの項目にnull | 0で変換 | MismatchedInputException | | LocalDateの書き出し | InvalidDefinitionException | “2026-09-27” | | 出力順（通常のクラス） | 宣言順 | アルファベット順 | | 出力順（record） | 宣言順 | 宣言順 | | 入れ子の深さの上限 | 1,000 | 500 | | 文字列1個の長さの上限 | 20,000,000 | 100,000,000 | | 設定の変更 | configure()で既存インスタンスを変更 | builder()／rebuild()で新規作成 | | 文字列値の取得 | asText()／textValue() | asString()／stringValue() | 影響が大きいのは未知項目の扱いです。2系で「APIのレスポンスに想定外の項目が増えたら例外で気づく」設計にしていた場合、3系では黙って通ります。同じ検知を続けたいなら、3系で`FAIL_ON_UNKNOWN_PROPERTIES`を明示的に有効にします。逆に、intの項目へのnullは2系だと0で素通りし、3系では例外になります。通常のクラスの出力順の変化（recordはどちらも宣言順のまま）は、JSON文字列をそのまま比較しているテストやAPIの署名計算を壊します。3系で宣言順に戻すには`MapperFeature.SORT_PROPERTIES_ALPHABETICALLY`を無効にします。3系の`asText()`は`@Deprecated`付きで残っているため、コンパイルは通り警告だけが出ます。 ### どちらを選ぶか：LTSとSpring Bootの管理版 FasterXMLの公式リリース表（Jackson-Releases）では、2.21系と3.1系がLTS（長期サポート）、2.22系と3.2系は最新ブランチ（LTSではない）と位置付けられています。2.21系は少なくとも2028年1月31日まで修正版が出る予定と明記されています。3.0系は2026年2月の3.1.0公開で終了しました。 - **3系を選ぶ**：Java 17以上で新規に作る場合、Spring Boot 4系を使う場合。Spring Boot 4.1.1が管理する版は3.1.5で、2系用の`spring-boot-jackson2`モジュールは説明文に「deprecated in favor of spring-boot-jackson」と書かれた非推奨扱いです。 - **2系を選ぶ**：Java 8・11が残る場合、Spring Boot 3系を使う場合（3.5.16の管理版は2.21.4）、2系前提のライブラリを多く抱える場合。 2系と3系はパッケージが違うため、同じクラスパスに共存させても衝突しません。2.22.3と3.2.3を同時に載せて両方のマッパーでJSONを読めることを確認しました。ライブラリが2系に依存したまま、アプリ側だけ3系へ移る段階的な移行が可能です。Spring Boot 4でのJackson 3対応の全体像は[Spring Boot 4の変更点と新機能の解説](/tech/details/10124/)で扱っています。 ## ObjectMapperによるJSONとJavaオブジェクトの相互変換 型が決まっているJSONは、ObjectMapperでrecordやクラスへ直接変換するのが最短です。`readValue`で読み、`writeValueAsString`で書きます。リストのように要素型が必要なものは`TypeReference`で型を渡します（以下は2系のコードで、recordを使うためJava 16以上が必要です。Java 8・11では通常のクラスで型を定義してください）。 ``` import com.fasterxml.jackson.core.type.TypeReference; import com.fasterxml.jackson.databind.ObjectMapper; import java.util.List; public class BindExample { // 変換用の型。record でもクラスでもよい public record User(String name, int age) {} // ObjectMapper は生成コストが高いので1つを使い回す private static final ObjectMapper MAPPER = new ObjectMapper(); public static void main(String[] args) throws Exception { // JSON文字列 → Javaオブジェクト User user = MAPPER.readValue("{\"name\":\"Sato\",\"age\":31}", User.class); System.out.println(user); // Javaオブジェクト → JSON文字列 System.out.println(MAPPER.writeValueAsString(new User("Suzuki", 28))); // 配列はTypeReferenceで要素の型を渡す List users = MAPPER.readValue( "[{\"name\":\"A\",\"age\":1},{\"name\":\"B\",\"age\":2}]", new TypeReference>() {}); System.out.println(users.size() + " " + users.get(1).name()); } } ``` ``` User[name=Sato, age=31] {"name":"Suzuki","age":28} 2 B ``` recordはアノテーション無しでコンストラクタ経由で変換されます。recordの仕組みは[Javaのレコードクラス（record）の解説](/tech/details/3254/)を参照してください。ObjectMapperをリクエストごとに`new`すると、型ごとの変換器のキャッシュが毎回捨てられます。設定を済ませたものを`static final`で共有するのが定石です。 ## JsonNodeによるJSONの解析と値の取得 大きなJSONの一部だけを読み、メモリ使用量を抑えたい場合はJsonParserによる逐次処理を検討します。項目が可変で、全体をメモリ上に保持できるJSONは、`readTree`でJsonNodeのツリーにして辿ります。クラスを定義しなくて済むのが利点です。 ``` import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; public class TreeExample { public static void main(String[] args) throws Exception { ObjectMapper mapper = new ObjectMapper(); String json = "{\"user\":{\"name\":\"Sato\",\"age\":31,\"tags\":[\"java\",\"maven\"]},\"score\":null}"; JsonNode root = mapper.readTree(json); System.out.println(root.get("missing")); // null System.out.println(root.path("missing").isMissingNode()); // true System.out.println(root.get("score").isNull()); // true（JSONのnull） JsonNode user = root.path("user"); System.out.println(user.path("name").asText()); // Sato System.out.println(user.path("age").asInt()); // 31 System.out.println(user.path("age").textValue()); // null（数値ノードなので） System.out.println(root.path("nope").path("deep").asInt(-1)); // -1（途中が無くても例外にならない） System.out.println(root.at("/user/tags/1").asText()); // maven for (JsonNode tag : user.path("tags")) { System.out.println("tag=" + tag.asText()); } } } ``` ### get()とpath()の違い 存在しないキーに対して、`get()`はJavaの`null`を返し、`path()`は`MissingNode`を返します。`get()`を連鎖させると途中で`NullPointerException`になるので、深い階層を辿るときは`path()`を使います。JSON側に`"score":null`と書かれている場合は、`get()`でも`null`ではなく`NullNode`が返り、`isNull()`がtrueになります。「キーが無い」と「値がnull」を区別したいときは、この2つを使い分けます。 ### asText()・textValue()・asInt()の戻り値 `asText()`や`asInt()`は型を変換して返し、変換できなければ既定値（空文字や0、引数で指定した値）を返します。`textValue()`は文字列ノードのときだけ値を返し、数値ノードでは`null`です。3系ではそれぞれ`asString()`と`stringValue()`に改名され、`stringValue()`は数値ノードに対して`null`ではなく`JsonNodeException`を投げます。型チェックが厳しくなった点は、移行時にテストで拾っておきたい差です。 ### at()とJSON Pointerによる深い階層の値の取得 `at("/user/tags/1")`のように、RFC 6901のJSON Pointerで位置を1回で指定できます。配列は0始まりの添字で、存在しない位置では`MissingNode`が返ります。配列ノードはそのまま拡張for文で回せます。 ## ObjectNode・ArrayNodeによるJSONの編集と文字列化 読み込んだJsonNodeは参照用の型なので、編集するときは`ObjectNode`（オブジェクト）や`ArrayNode`（配列）にキャストします。 ``` import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; public class EditExample { public record User(String name, int age) {} public static void main(String[] args) throws Exception { ObjectMapper mapper = new ObjectMapper(); ObjectNode root = (ObjectNode) mapper.readTree( "{\"user\":{\"name\":\"Sato\",\"age\":31,\"tags\":[\"java\"]},\"score\":null}"); root.put("active", true); // 追加・上書き root.remove("score"); // 削除 ((ArrayNode) root.path("user").path("tags")).add("maven"); // 配列に追加 root.putObject("meta").put("version", 2); // 子オブジェクトを作って追加 root.withObject("/audit/created").put("by", "batch"); // 途中の階層もまとめて作る System.out.println(mapper.writeValueAsString(root)); System.out.println(mapper.writerWithDefaultPrettyPrinter().writeValueAsString(root.path("meta"))); // ツリーとJavaオブジェクトの相互変換 ObjectNode userNode = (ObjectNode) root.path("user").deepCopy(); userNode.remove("tags"); // User に無い項目は外す（2系は未知項目で例外） User user = mapper.treeToValue(userNode, User.class); JsonNode back = mapper.valueToTree(user); System.out.println(user + " " + back); } } ``` ``` {"user":{"name":"Sato","age":31,"tags":["java","maven"]},"active":true,"meta":{"version":2},"audit":{"created":{"by":"batch"}}} { "version" : 2 } User[name=Sato, age=31] {"name":"Sato","age":31} ``` 文字列に戻すのは`writeValueAsString`、整形するなら`writerWithDefaultPrettyPrinter()`です。`treeToValue`はツリーをrecordへ、`valueToTree`はオブジェクトをツリーへ変換します。途中で`tags`を外しているのは、2系の既定では`User`に無い項目があると`UnrecognizedPropertyException`になるためです。外さずに実行すると、実際にこの例外で止まりました。 ## 例外処理と失敗しやすい3つのパターン ### 検査例外の2系と非検査例外の3系 2系の`readTree`や`readValue`は`JsonProcessingException`（`IOException`のサブクラス）を宣言しているため、`catch`か`throws`が必須です。3系では`JacksonException`が`RuntimeException`を継承しており、ラムダやStreamの中でも包まずに呼べます。 ``` import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; public class ErrorExample { public static void main(String[] args) { ObjectMapper mapper = new ObjectMapper(); try { JsonNode node = mapper.readTree("{\"a\":1,}"); // 末尾カンマは不正なJSON System.out.println(node); } catch (JsonProcessingException e) { // 2系は検査例外なのでcatchかthrowsが必須 System.out.println(e.getClass().getSimpleName() + ": " + e.getOriginalMessage()); } } } ``` ``` JsonParseException: Unexpected character ('}' (code 125)): was expecting double-quote to start field name ``` 3系で同じ入力を渡すと、例外クラスは`tools.jackson.core.exc.StreamReadException`になり、メッセージの「field name」も「property name」に変わります。例外メッセージの文字列で分岐しているコードは、移行時に見直しが必要です。 ### jackson-coreの版ずれで起きるNoClassDefFoundError databindとcoreの版が食い違うと、コンパイルは通るのに実行時に落ちます。databind 2.22.3に対してcore 2.12.7を直接指定したpomで試すと、Mavenは直接指定した2.12.7を優先し、最初のJSON変換で次の例外が出ました。 ``` Exception in thread "main" java.lang.NoClassDefFoundError: com/fasterxml/jackson/core/exc/StreamConstraintsException at com.fasterxml.jackson.databind.deser.std.JdkDeserializers.(JdkDeserializers.java:31) ``` 実務では、古いcoreを引く別ライブラリが依存ツリーの浅い位置にあるとこの状態になります。`mvn dependency:tree -Dincludes=com.fasterxml.jackson.core`で版を確認し、ずれていればjackson-bomで揃えます。 ### 入れ子の深さと文字列長の上限 Jacksonは2.15以降、巨大な入力による資源枯渇を防ぐため読み込みに上限を設けています。既定値を`StreamReadConstraints.defaults()`で読むと、2.22.3は入れ子1,000段・文字列2,000万文字、3.2.3は入れ子500段・1億文字でした。3.2.3に1,000段の配列を渡すと「Document nesting depth (501) exceeds the maximum allowed (500…)」で失敗します。2系で動いていた深いJSONが3系で読めなくなる場合は、次のように上限を明示します（2系の例）。 ``` JsonFactory factory = JsonFactory.builder() .streamReadConstraints(StreamReadConstraints.builder().maxNestingDepth(2000).build()) .build(); ObjectMapper deep = new ObjectMapper(factory); ``` 上限を引き上げる場合も、入力の深さと使用可能なメモリに合わせた有限値を設定します。外部から受け取るJSONを任意の型へ変換する設定（デフォルトタイピング）は、上限とは別にリモートコード実行の入口になり得ます。この危険は[安全でないデシリアライゼーションの仕組みと防御実装](/tech/details/16369/)で扱っています。 ## Jackson 3系で同じ処理を書く場合 3系では`JsonMapper.builder()`で設定を決めてから生成し、生成後は変更できません。設定違いが欲しいときは`rebuild()`で別インスタンスを作ります。2系の挙動に寄せたい設定も、ここで明示します。 ``` import tools.jackson.core.JacksonException; import tools.jackson.databind.DeserializationFeature; import tools.jackson.databind.JsonNode; import tools.jackson.databind.json.JsonMapper; import java.time.LocalDate; public class Jackson3Example { public record Event(String title, LocalDate date) {} public static void main(String[] args) { // 3系は非検査例外なので throws 不要 JsonMapper mapper = JsonMapper.builder() .enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) // 2系と同じく未知項目を例外にする .build(); // java.time は追加モジュールなしで ISO 形式になる System.out.println(mapper.writeValueAsString(new Event("release", LocalDate.of(2026, 9, 27)))); JsonNode root = mapper.readTree("{\"name\":\"Sato\",\"age\":31}"); System.out.println(root.path("name").asString()); // 2系の asText() に相当 // 設定を変えるときは rebuild() で別インスタンスを作る JsonMapper lenient = mapper.rebuild() .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) .build(); System.out.println(lenient.readValue("{\"title\":\"a\",\"date\":\"2026-01-01\",\"x\":1}", Event.class)); try { mapper.readValue("{\"title\":\"a\",\"date\":\"2026-01-01\",\"x\":1}", Event.class); } catch (JacksonException e) { System.out.println(e.getClass().getSimpleName()); } } } ``` ``` {"title":"release","date":"2026-09-27"} Sato Event[title=a, date=2026-01-01] UnrecognizedPropertyException ``` 2系で`LocalDate`を扱うには`jackson-datatype-jsr310`を追加して`JavaTimeModule`を登録します。ただし2系は登録しただけだと`[2026,9,27]`という配列で書き出し、`"2026-09-27"`にするには`SerializationFeature.WRITE_DATES_AS_TIMESTAMPS`の無効化が別に必要でした。3系はこの2手間が不要です。 ## よくある質問 ### jackson-coreやjackson-annotationsも依存に書くべきですか？ 通常は書きません。`jackson-databind`だけで推移的に入ります。版を固定したい事情があるなら、個別に書くよりjackson-bomをimportしてください。個別指定はcoreだけ古い版になる事故の元です。 ### ObjectMapperはスレッドセーフですか？ 2系のJavadocには「最初の読み書きの前に全ての設定を終えていればスレッドセーフ」と書かれています。起動時に設定して共有し、途中で`configure()`を呼ばない限り複数スレッドから使えます。3系のマッパーは生成後に設定を変えられないので、この制約を意識する必要がありません。 ### Spring Bootでは自分でJacksonを追加する必要がありますか？ `spring-boot-starter-web`などのスターターに含まれるので、追加は不要です。Spring Bootは自前のObjectMapper（4系ではJsonMapper）をBeanとして用意し、`spring.jackson.*`のプロパティで設定を変えられます。Spring Bootの依存の書き方は[Spring Bootの4.1系の依存名と最小Web APIの作り方](/tech/details/17478/)にまとめています。 ### JsonNodeのtoString()とwriteValueAsString()は同じ結果になりますか？ 2.22.3と3.2.3では、エスケープを含め同じ正しいJSON文字列を返しました。整形したい場合は2系の`toPrettyString()`か`writerWithDefaultPrettyPrinter()`を使います。ObjectMapperに独自の設定（出力時の数値形式など）を入れているときは、その設定を通る`writeValueAsString()`を使うほうが確実です。 ### Mavenでjackson-databindの最新版を確認する方法は？ Maven Centralの`maven-metadata.xml`にある``は非SNAPSHOT版を示しますが、RC版などを含む場合があり、正式安定版とは限りません。採用する版はFasterXMLの公式リリース表（Jackson-Releases）でも確認してください。databindの``は2026年9月27日時点で2系が2.22.3、3系が3.2.3で、どちらも正式版でした。前述のとおりannotationsは``自体がRC版を指しているため、databindの値を見てください。JDKの版を切り替えて試す場合は[SDKMAN!によるJVMツールのバージョン管理](/tech/details/11413/)が便利です。 ## 関連記事 - [Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いを解説【2026年最新】](/tech/details/10124/) - [Spring Bootとは｜4.1系の依存名の変更と最小Web APIの作り方](/tech/details/17478/) - [Javaのレコードクラス（record）とは？使い方・コンストラクタ・継承できない理由をJava 25で実測](/tech/details/3254/) - [安全でないデシリアライゼーションとは？RCEに至る仕組みと言語別の防御実装を解説](/tech/details/16369/) - [JVM開発者がSDKMAN!を導入すべき理由とバージョン管理の課題解消](/tech/details/11413/) --- 出典: [JacksonをMavenで導入する手順｜2.22と3.2の依存の違いとObjectMapper・JsonNodeの使い方]()（株式会社一創）