• 无法提供足够的信息，为什么这个 API 被废弃了？需要用哪个 API 代替？毕竟文档注释不是强制性的。

对于这个问题，Kotlin 的解决方案是 kotlin.Deprecated 注解，它比 java.lang.Deprecated更强大、更人性化。

kotlin.Deprecated的声明如下：

@Target(CLASS, FUNCTION, PROPERTY, ANNOTATION_CLASS, CONSTRUCTOR, PROPERTY_SETTER, PROPERTY_GETTER, TYPEALIAS)
@MustBeDocumented
public annotation class Deprecated(
val message: String,
val replaceWith: ReplaceWith = ReplaceWith(“”),
val level: DeprecationLevel = DeprecationLevel.WARNING
)
  • @Target 表示 Deprecated可以用在类、函数、属性、注解类、构造函数、getter、setter 和类型别名上；
  • @MustBeDocument表示Deprecated是个公开的 API，必需包含在 API 文档里。

我们重点看三个参数：

第一个参数很简单，String 类型的 message，需要在这里说明废弃的原因。

@Deprecated(“this function is deprecated!”)
fun oldAdd(a: Int, b: Int) {
println(a + b)
}
fun main(args: Array) {
oldAdd(1, 2)
}

比如我们定义了上面的函数 oldAdd，用 Deprecated 标注一下，如果调用这个函数，就会出现编译警告：

Warning:(7, 5) Kotlin: ‘oldAdd(Int, Int): Unit’ is deprecated. this function is deprecated!

我们定义 Deprecated 时给的 this function is deprecated! 出现在了警告信息里，让我们排查问题方便不少。

第三个参数是DeprecationLevel这个枚举里定义的三个废弃级别之一，在使用了 Deprecated API 的地方给出不同级别的警告 ：

public enum class DeprecationLevel {
WARNING,
ERROR,
HIDDEN
}
  • WARNING：默认选项，编译依然会成功，但会出现编译警告；
  • ERROR：编译错误，相当于禁止使用这个 API；
  • HIDDEN：隐藏，无法调用这个 API。

我们把上面的代码改一下，加上自定义的废弃级别：

@Deprecated(
“this function is deprecated!”,
ReplaceWith(“”), // 无法省略
level = DeprecationLevel.ERROR
)
fun oldAdd(a: Int, b: Int) {
println(a + b)
}

再编译就会出现编译错误，编译直接失败：

Error:(11, 5) Kotlin: Using ‘oldAdd(Int, Int): Unit’ is an error. this function is deprecated!

如果换成HIDDEN：

Error:(11, 5) Kotlin: Unresolved reference: oldAdd

找不到这个函数了……

最后是第二个参数，需要是 ReplaceWith 类型，它是一个注解类型（因为注解的参数只能是基本类型、String 和注解类型）。声明如下：