📘

Kotlinの標準APIを知る【Deprecated編】

2021/12/13に公開

公式ドキュメント

https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecated/#kotlin.Deprecated

KotlinのDeprecatedアノテーションはJavaより便利

Javaに同じく@Deprecatedアノテーションが存在しますが、こちらはあくまで非推奨を伝えることに留まっている感じです。Java9以降、非推奨アノテートされた対象が将来取り除かれる可能性があるか等も表現できるようになったみたいですが、言ってしまうとそのくらいです。一方、Kotlinの独自の@Deprecatedはより多くのことを表現可能です。

Kotlinの@Deprecated

public annotation class Deprecated(
    val message: String,
    val replaceWith: ReplaceWith = ReplaceWith(""),
    val level: DeprecationLevel = DeprecationLevel.WARNING
)

message

参照時にIntelliJでホバーするとメッセージを表示できます。
こちらは至って普通でJava的にはJavaDocの@deprecatedと同様です。

replaceWith

https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-replace-with/

こちらはdepreactedされた実装の代替実装をexpressionという形式でアノテーションに登録しておくとIntelliJの機能で自動で代替実装の形式に切り替えてくれたりする優れものです。

JavaではJavaDocコメント等の中で代替実装について言及していたり、内部的に代替実装をコールする形でインターフェースはそのままに実装で表現していたりとわかりずらい部分をストレートに表現する機構を持ってくれています。おまけにIDEでのサポート付とは優秀です。

@Deprecated(
    message = "新APIのコールへ実装を切り替えてください",
    level = DeprecationLevel.WARNING,
    replaceWith = ReplaceWith("newApiPlusTen(value)")
)
fun oldApiPlusTen(value: String): Int {
    return value.toInt() + 10
}

こんな感じで定義した場合...

こんな感じでReplace with ~と新しいAPIに切り替えることをお勧めしてくれて実際にリンクを叩くとexpressionで定義した形式の実装に切り替わります。

level

https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecation-level/

  • WARNING
  • ERROR
  • HIDDEN

の三つからレベルを選択できます。

上から順番に
WARININGの場合はdeprecatedらしく取り消し線付で表示してくれます。
ERRORの場合はコンパイルエラーにしてくれます。
HIDDENの場合はそもそもアクセス不可=そんなものは無い扱いにしてくれます。

まとめ

kotlinの@Deprecatedは表現が多彩です。既存の実装を改善した新しいAPIを作ることで昔の実装を徐々に切り替えたい場合や、必要ない=賞味期限切れだけど廃棄できないコードの扱いに困るときなどJavaの現場開発で頭を少し抱えていた部分を少し上手く扱えそうな兆しを感じました。

Discussion