• 无法提供足够的信息,为什么这个 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 和注解类型)。声明如下: