我们都知道 Java 有一个java.lang.Deprecated注解，用来将一个 API 标记为“废弃”，或者说“不建议使用”。比如 String 类就有一个被标记为 Deprecated的构造函数：
@Deprecated
public String(byte ascii[], int hibyte) {this(ascii, hibyte, 0, ascii.length);
}
Java 还提供了一个 @deprecated 的文档标签，用于提供相关信息。
这个注解存在几个缺陷：
- 无法禁止使用废弃的 API，单单一个编译警告不可能阻止划水程序员；
- 无法提供足够的信息，为什么这个 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<String>) {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 和注解类型）。声明如下：
@Target()
@Retention(BINARY)
@MustBeDocumented
public annotation class ReplaceWith(val expression: String, vararg val imports: String)expression是要替换成的代码段，智能替换参数；imports是需要额外 import 的依赖。
定义一个函数newAdd，放进new包里：
package newfun newAdd(a: Int, b:Int) {println("$a + $b = ${a + b}")
}
然后修改一下oldAdd 函数：
@Deprecated("this function is deprecated!",ReplaceWith("newAdd(a, b)", "new.newAdd")
)
fun oldAdd(a: Int, b: Int) {println(a + b)
}
这样，我们在 IDEA 里就可以按 Alt + Enter 一键替换：
替换时会自动匹配参数，并导入 imports 中定义的依赖：
原文链接：https://zhuanlan.zhihu.com/p/32890550
