--- title: "StringUtils.equalsは非推奨？Strings.CS/CIへの移行と主要メソッド一覧【3.21.0対応】" url: "https://www.issoh.co.jp/tech/details/3716/" published: 2024-10-02 updated: 2026-10-15 categories: ["Java"] publisher: "株式会社一創" --- # StringUtils.equalsは非推奨？Strings.CS/CIへの移行と主要メソッド一覧【3.21.0対応】 Apache Commons Lang（commons-lang3）の`StringUtils.equals`は、2025年7月リリースの3.18.0から**非推奨（@Deprecated）**です。2026年9月25日公開の最新3.21.0でも非推奨のままですが、削除はされておらず呼び出せば従来どおり動きます。移行先は`Strings.CS.equals`（大文字小文字を区別）、`equalsIgnoreCase`は`Strings.CI.equals`です。この記事では、非推奨になった理由と対応表、`Objects.equals`との差、Spring Bootで警告が出ない理由を、JDK 25と3.21.0で実行した結果つきで説明します。 ## まとめ：StringUtils.equalsの非推奨と移行の要点 - 3.18.0で`equals`／`equalsIgnoreCase`／`contains`／`replace`／`indexOf`／`startsWith`など40個（オーバーロードを含む）のメソッドが非推奨になった。最新3.21.0でも同じで、削除はされていない。 - 移行先は`Strings.CS`（大小を区別）と`Strings.CI`（大小を無視）。`equals`は`Strings.CS.equals`、`equalsIgnoreCase`は`Strings.CI.equals`へ置き換える。 - `Objects.equals`で置き換えられるのは、比べる値が`String`か`null`の箇所。`StringBuilder`と比べると中身が同じでも`false`を返す。 - `isEmpty`／`isBlank`／`substring`／`split`／`strip`／`right`／`abbreviate`などは非推奨ではない。 - Spring Boot 3.5系はcommons-lang3を3.17.0に固定しているため、非推奨の警告が出ず、`Strings`クラスも存在しない。 - javacの既定では「Note」が2行出るだけでコンパイルは成功する。失敗するのは`-Xlint:deprecation`で警告を有効にし、`-Werror`も指定した構成だけ（`-Werror`単独では成功した）。 ## StringUtils.equalsが非推奨になった理由（3.18.0の設計変更） 3.18.0で新設された[Stringsクラス](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/Strings.html)は、大小を区別する`Strings.CS`（Case-Sensitive）と大小を無視する`Strings.CI`（Case-Insensitive）の2つのインスタンスを持ちます。`equals`と`equalsIgnoreCase`、`contains`と`containsIgnoreCase`のように、大小の扱いだけが違うメソッドが`StringUtils`に2本ずつ並んでいた状態を、インスタンスの選択（CSかCIか）で表す形に改めたのが理由です。 非推奨の数はソースで確かめられます。3.17.0の`StringUtils.java`で`@Deprecated`が付いた`public static`メソッドは13個でしたが、3.18.0では53個に増え、3.21.0も53個のままでした。増えた40個（オーバーロードを含む）が今回の移行対象で、移行先はほぼすべて`Strings.CS`か`Strings.CI`です。[StringUtilsのJavadoc](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html)では`equals`に「Use Strings.CS.equals(CharSequence, CharSequence).」と書かれており、実装も`Strings.CS.equals`を呼ぶだけです。 ### 削除ではなく動作は継続（LANG-1777と3.21.0の状況） 非推奨の付いたメソッドは削除予定が告知されておらず、バイナリ互換も保たれています。一括の非推奨化には利用者側の反発があり、取り消しを求める[LANG-1777「Revert deprecations of 3.18.0」](https://issues.apache.org/jira/browse/LANG-1777)が起票されました。2026年10月15日時点でこのチケットはReopened（未解決）で、修正バージョンも空のままです。[3.21.0のリリースノート](https://commons.apache.org/proper/commons-lang/changes.html)にも非推奨を取り消す変更はありません。取り消しを待つより、新しく書くコードから`Strings`に寄せる方が無駄がありません。 ### javacの警告の出方（既定・-Xlint:deprecation・-Werror） JDK 25.0.4でcommons-lang3 3.21.0を相手に`StringUtils.equals`を1回呼ぶクラスをコンパイルすると、オプションごとに次の出力になりました。 ``` $ javac -cp commons-lang3-3.21.0.jar Demo.java Note: Demo.java uses or overrides a deprecated API. Note: Recompile with -Xlint:deprecation for details. $ javac -Xlint:deprecation -cp commons-lang3-3.21.0.jar Demo.java Demo.java:8: warning: [deprecation] equals(CharSequence,CharSequence) in StringUtils has been deprecated 1 warning $ javac -Xlint:deprecation -Werror -cp commons-lang3-3.21.0.jar Demo.java error: warnings found and -Werror specified 1 error ``` 既定のままなら「Note」が出るだけで、classファイルは生成されます。`-Werror`だけを付けた場合も、非推奨は「Note」の扱いのままなので成功しました。ビルドが止まるのは、`-Xlint:deprecation`で警告を有効にしたうえで、`-Werror`（Mavenなら`failOnWarning`、Gradleなら`options.compilerArgs`への指定）を有効にしている構成です。 ## 非推奨メソッドと移行先の対応表（Strings.CS / Strings.CI） 3.21.0で非推奨になっている主なメソッドと置き換え先です。使うには`import org.apache.commons.lang3.Strings;`を追加します。`Strings`のメソッドは`static`ではないので、`Strings.CS.equals(...)`のようにインスタンス経由で呼びます。 | 非推奨（StringUtils） | 移行先 | | --------------------------------------------- | -------------------------------------------------------- | | equals | Strings.CS.equals | | equalsIgnoreCase | Strings.CI.equals | | equalsAny / equalsAnyIgnoreCase | Strings.CS.equalsAny / Strings.CI.equalsAny | | compare / compareIgnoreCase | Strings.CS.compare / Strings.CI.compare | | contains（CharSequence検索） / containsIgnoreCase | Strings.CS.contains / Strings.CI.contains | | containsAny（CharSequence…） | Strings.CS.containsAny | | indexOf / lastIndexOf（CharSequence検索） | Strings.CS.indexOf / Strings.CS.lastIndexOf | | startsWith / endsWith | Strings.CS.startsWith / Strings.CS.endsWith | | replace / replaceOnce | Strings.CS.replace / Strings.CS.replaceOnce | | removeStart / removeEnd | Strings.CS.removeStart / Strings.CS.removeEnd | | appendIfMissing / prependIfMissing | Strings.CS.appendIfMissing / Strings.CS.prependIfMissing | 表のIgnoreCase版（`startsWithIgnoreCase`、`removeEndIgnoreCase`など）は、すべて`Strings.CI`の同名メソッドに対応します。 ### equalsの書き換えとObjects.equalsとの違い（実行結果） 3.21.0とJDK 25で、移行先と標準ライブラリの比較メソッドを並べて実行しました。以下はメソッド内に置く抜粋で、コメントは戻り値です。実行にはStringUtils、Strings、java.util.Objectsのimportが必要です。 ``` StringBuilder sb = new StringBuilder("abc"); StringUtils.equals("abc", sb); // true（非推奨） Strings.CS.equals("abc", sb); // true Objects.equals("abc", sb); // false "abc".contentEquals(sb); // true Strings.CS.equals(null, null); // true Objects.equals(null, null); // true ``` `Objects.equals(a, b)`は内部で`a.equals(b)`を呼ぶため、`String`と`StringBuilder`のように型が違うと中身が同じでも`false`になります。`StringUtils.equals`と`Strings.CS.equals`は文字の並びで比べるので`true`です。比べる両方が`String`だと確定している箇所は`Objects.equals`で標準ライブラリに寄せてよく、`CharSequence`型の引数や`StringBuilder`が混ざる箇所は`Strings.CS.equals`に置き換えるのが安全です。 ### equalsIgnoreCase・contains・replaceの移行例 ``` Strings.CI.equals("abc", "ABC"); // true（旧 equalsIgnoreCase） Strings.CS.equalsAny("b", "a", "b"); // true（旧 equalsAny） Strings.CI.containsAny("Hello", "xx", "LL"); // true（旧 containsAnyIgnoreCase） Strings.CS.replace("aXbX", "X", "-"); // "a-b-"（旧 replace） Strings.CI.removeEnd("report.CSV", ".csv"); // "report"（旧 removeEndIgnoreCase） ``` IDEの一括置換で移すときに間違えやすいのは、`IgnoreCase`付きのメソッドを`Strings.CS`に寄せてしまうことです。メソッド名から`IgnoreCase`が消えるため、置換後のコードだけを見てもCSとCIの取り違えに気づけません。置換前に非推奨のシグネチャを確認し、対象の呼び出しだけを「IgnoreCase付き→CI」「それ以外→CS」に分けて移行します。置換後は大文字小文字を含む入力で結果を確認してください。 ### compareでnullを後ろに並べる指定（Strings.builder） `Strings.CS`と`Strings.CI`は、`compare`で`null`を小さい値として扱います。旧`StringUtils.compare(str1, str2, false)`のように`null`を大きい値として扱いたいときは、`Strings.builder()`で専用のインスタンスを作ります。 ``` Strings.CS.compare(null, "a"); // -1（nullが先） Strings nullLast = Strings.builder() .setIgnoreCase(false) .setNullIsLess(false) .get(); nullLast.compare(null, "a"); // 1（nullが後） ``` 3つ引数を取る`StringUtils.compare(String, String, boolean)`は3.21.0でも非推奨ではありません。非推奨なのは2引数の`compare`だけです。 ## StringUtilsの打ち消し線とimport先の違い `StringUtils`という名前のクラスは複数のライブラリにあり、IDEの補完で別物をimportしていることがあります。打ち消し線や挙動の違いに気づいたら、まずimport文のパッケージを確かめてください。 | パッケージ | 非推奨の状況 | equals(null, null) | | ------------------------------- | ------------------- | ------------------ | | org.apache.commons.lang3 | equals等は3.18.0から非推奨 | true | | org.apache.commons.lang（2.x） | ライブラリごと旧版 | true | | org.springframework.util | isEmptyが5.3から非推奨 | equalsなし | | software.amazon.awssdk.utils | 非推奨なし | false | | org.apache.commons.codec.binary | 非推奨なし | true | ### 旧commons-lang（2.x）の識別と移行 import文が`org.apache.commons.lang.StringUtils`（末尾が`lang`）なら、lang3とは別のレガシーライブラリです。2.xは2011年の2.6が最後の版で、[CVE-2025-48924](https://github.com/advisories/GHSA-j288-q9x7-2f5v)の影響範囲にも「commons-lang 2.0から2.6」が含まれています。CVEの公表文では、修正を含むlang3の3.18.0への更新が推奨されています。 ### SpringのStringUtils.isEmptyの非推奨化と代替API 「StringUtils.isEmpty 非推奨」で調べている場合、多くはSpring Frameworkの`org.springframework.util.StringUtils`です。[SpringのisEmpty(Object)](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/StringUtils.html)は5.3で`@Deprecated(since = "5.3")`になり、`hasLength`や`hasText`などが代替として案内されています。String型の値で従来の空判定を保つには`!StringUtils.hasLength(value)`を使います。`!StringUtils.hasText(value)`は空白だけの文字列も空と判定するため、意味が変わります。commons-lang3の`isEmpty`は非推奨ではないので、移行先も別物です。 ### AWS SDKとcommons-codecのStringUtils.equalsにおけるnull比較 AWS SDK for Java v2の`software.amazon.awssdk.utils.StringUtils.equals`は、引数の片方でも`null`なら`false`を返し、両方`null`でも`false`です。この挙動はJavadocと食い違っていると[issue #6603](https://github.com/aws/aws-sdk-java-v2/issues/6603)で報告され、メンテナーは2026年1月5日のコメントで、戻り値を変えると破壊的変更になるとしてJavadoc側を実装に合わせたと説明しています。utils 2.56.0のソースでも、Javadocの例は`StringUtils.equals(null, null) = false`で、実装も同じです。commons-codecの`org.apache.commons.codec.binary.StringUtils.equals`は1.23.0でも非推奨ではなく、両方`null`で`true`を返します。lang3から移るつもりでこの2つに置き換えると、`null`の扱いが変わる場合があります。 ## Spring Bootで警告が出ない・Stringsが見つからない原因（BOMが固定する版） Spring Bootの依存管理（BOM）はcommons-lang3の版を決めています。各系列の最新版の`spring-boot-dependencies`のpomを読むと、次の値でした。 | Spring Boot | commons-lang3 | Strings | equalsの非推奨 | | ----------- | ------------- | ------- | ---------- | | 3.5.16 | 3.17.0 | なし | 出ない | | 4.0.8 | 3.19.0 | あり | 出る | | 4.1.1 | 3.20.0 | あり | 出る | [Spring Boot 3.5.16のpom](https://repo1.maven.org/maven2/org/springframework/boot/spring-boot-dependencies/3.5.16/spring-boot-dependencies-3.5.16.pom)は`commons-lang3.version`を3.17.0にしています。Maven 3.9.11で`spring-boot-starter-parent` 3.5.16を親にし、版を書かずにcommons-lang3を追加すると、解決される版は3.17.0でした。この構成では`StringUtils.equals`に打ち消し線は出ず、記事やAIの回答どおり`Strings.CS.equals`に書き換えると、コンパイルで`error: cannot find symbol`（`import org.apache.commons.lang3.Strings;`の行）になります。Spring Bootの各系列のサポート期限は[Spring Bootバージョン一覧とサポート期限（EOL）【2026年10月】最新版は4.1、4.0の無償サポートは12月末終了](/tech/details/5172/)にまとめています。 ### 実行時のNoClassDefFoundError 3.21.0でコンパイルしたクラスを3.17.0のjarで実行すると、非推奨の`StringUtils.equals`までは動き、次の`Strings.CS.equals`の行で止まりました。 ``` Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/commons/lang3/Strings at Demo.main(Demo.java:9) Caused by: java.lang.ClassNotFoundException: org.apache.commons.lang3.Strings ``` ライブラリを作っていて利用側のアプリケーションが版を決める場合や、アプリケーションサーバーが共通ライブラリとして古いlang3を持っている場合に起きます。`mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3`で、実際に解決される版を確認してから移行してください。 ### Spring Bootで管理版を上書きする方法 `spring-boot-starter-parent`を使うMavenプロジェクトでは、`properties`で版を上書きできます。Maven 3.9.11とSpring Boot 3.5.16で、この指定により解決される版が3.17.0から3.21.0に変わることを確認しました。 ``` 3.21.0 ``` Gradleで`io.spring.dependency-management`プラグインを使っている場合は、`build.gradle`に`ext['commons-lang3.version'] = '3.21.0'`を書きます。 ## 非推奨ではない主要メソッドの実行結果 大小の2系統を持たないメソッドは非推奨の対象外です。3.21.0で実行した結果を示します。 ``` StringUtils.isEmpty(" "); // false（空白1文字は空ではない） StringUtils.isBlank(" "); // true StringUtils.substring("abc", 5); // ""（範囲外でも例外なし） StringUtils.split("a,,b", ","); // [a, b]（空要素を除く） StringUtils.splitPreserveAllTokens("a,,b", ","); // [a, , b] StringUtils.right("2026-10-15", 5); // "10-15" StringUtils.right(null, 5); // null StringUtils.abbreviate("commons-lang3", 8); // "commo..." StringUtils.isNumeric("１２３"); // true（全角数字も数字扱い） StringUtils.isNumeric("-1"); // false（符号は不可） StringUtils.defaultIfBlank(" ", "N/A"); // "N/A" ``` 見落としやすいのは`split`と`isNumeric`です。`split`は連続した区切り文字の間の空要素を捨てるので、空欄に意味がある単純な区切り文字列では`splitPreserveAllTokens`を使います。引用符内のカンマや改行を含むCSVには、Apache Commons CSVなどのCSVパーサーを使ってください。`isNumeric`は全角の「１２３」を`true`と判定するため、`Integer.parseInt`の前のチェックに使うと、全角数字がそのまま渡ります。 ### stripとtrimの違い（全角スペース） ``` StringUtils.strip("　全角　"); // "全角" StringUtils.trim("　全角　"); // "　全角　"（全角スペースが残る） ``` `strip`は`Character.isWhitespace`で判定するため全角スペース（U+3000）も取り除きます。`trim`は`String.trim`と同じく文字コード32以下だけを取り除くので、全角スペースは残ります。日本語のフォーム入力を正規化するなら`strip`を使います。 ## 移行するかの判断基準（急ぐ場面と急がない場面） 動いている既存コードを、警告を消すためだけに一斉に書き換える必要はありません。対応は、警告によるビルド失敗、脆弱性対策のための更新、利用側との互換性維持に分けて判断します。 - `-Xlint:deprecation`と`-Werror`（または`failOnWarning`）で警告をエラー扱いにしていて、lang3を3.18.0以上に上げる予定がある。 - lang3が3.18.0未満のまま残っている。[CVE-2025-48924](https://github.com/advisories/GHSA-j288-q9x7-2f5v)（`ClassUtils.getClass`に非常に長い文字列を渡すと`StackOverflowError`）は3.0以上3.18.0未満が対象です。非推奨の警告を避けるために3.17.0に留めると、この修正も受けられません。 - ライブラリとして配布していて、利用側のlang3の版を選べない。この場合は逆に`Strings`を使わず、`StringUtils`のまま書く方が`NoClassDefFoundError`を避けられます。 それ以外の場面では、新しく書くコードを`Strings.CS`／`Strings.CI`で書き、既存コードは触ったファイルから順に置き換えれば足ります。複数のモジュールで共通部品の版がそろっていない業務システムでは、まず依存の版を一本にそろえる方が先です。Javaの業務システムの改修や新規構築を外部に相談したい場合は、[フルスクラッチ開発](/service/system/fullscratch/)の支援内容も参考にしてください。 ## Apache Commons Lang3の導入（Maven / Gradle） 2026年10月15日時点の最新版は3.21.0です（[Maven Central](https://central.sonatype.com/artifact/org.apache.commons/commons-lang3/3.21.0)）。`Strings`クラスは3.18.0以上にしか無く、jarのクラスファイルはJava 8（major version 52）向けにコンパイルされているので、Java 8の環境でも使えます。 ``` org.apache.commons commons-lang3 3.21.0 ``` ``` implementation("org.apache.commons:commons-lang3:3.21.0") ``` Mavenでの依存追加の流れは[JacksonをMavenで導入する手順｜2.22と3.2の依存の違いとObjectMapper・JsonNodeの使い方](/tech/details/3825/)と同じ要領です。Gradleでコンパイルに使うJDKの版をそろえる方法は[ツールチェーン(toolchain)とは？構成要素と言語別の実例・GradleのJava Toolchain設定](/tech/details/7073/)で扱っています。 ## よくある質問 ### StringUtils.equalsは将来削除されますか？ 2026年10月15日時点で削除の予定は告知されていません。最新の3.21.0でも`@Deprecated`が付いているだけで動作します。非推奨の取り消しを求めるLANG-1777は未解決のままです。 ### StringUtils.equalsの代わりにObjects.equalsを使っても大丈夫ですか？ 比べる両方が`String`なら同じ結果です。文字の並びが同じ`String`と`StringBuilder`を比べると`Objects.equals`は`false`、`Strings.CS.equals`は`true`を返すため、`CharSequence`が混ざる箇所は`Strings.CS.equals`に置き換えてください。 ### StringUtils.isEmptyやisBlankも非推奨ですか？ commons-lang3の`isEmpty`／`isBlank`／`isNotBlank`は非推奨ではありません。非推奨なのはSpring Frameworkの`org.springframework.util.StringUtils.isEmpty`で、5.3から`hasLength`／`hasText`への移行が案内されています。真偽が逆になるので`!StringUtils.hasLength(value)`と否定して置き換えます。 ### equalsIgnoreCaseの移行先は何ですか？ `Strings.CI.equals(s1, s2)`です。CIはCase-Insensitive（大文字小文字を無視）の略で、旧`equalsIgnoreCase`と同じ結果になります。 ### Strings.CS.equalsが見つからないと言われるのはなぜですか？ 使っているcommons-lang3が3.18.0未満です。Spring Boot 3.5系は既定で3.17.0を使うため、`commons-lang3.version`プロパティで3.18.0以上に上書きしてください。 ## 関連記事 - [Spring Bootバージョン一覧とサポート期限（EOL）【2026年10月】最新版は4.1、4.0の無償サポートは12月末終了](/tech/details/5172/) - [JacksonをMavenで導入する手順｜2.22と3.2の依存の違いとObjectMapper・JsonNodeの使い方](/tech/details/3825/) - [ツールチェーン(toolchain)とは？構成要素と言語別の実例・GradleのJava Toolchain設定](/tech/details/7073/) - [Lombokとは？Javaのアノテーションでボイラープレートを削減する仕組みと使い方](/tech/details/3300/) --- 出典: [StringUtils.equalsは非推奨？Strings.CS/CIへの移行と主要メソッド一覧【3.21.0対応】]()（株式会社一創）