Day724. 如何改进代码废弃 -Java8后最重要新特性

Posted 2022-08-31 阿昌喜欢吃黄桃

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Day724. 如何改进代码废弃 -Java8后最重要新特性相关的知识，希望对你有一定的参考价值。

如何改进代码废弃

Hi，我是阿昌，今天学习记录的是关于如何改进代码废弃。

像所有的事物一样，公开接口也有生命周期。

要废弃那些被广泛使用的、或者还有人使用的公开接口，是一个非常痛苦的过程。

该怎么废弃一个公开接口，该怎么减少废弃接口的影响呢？

一、阅读案例

在 JDK 中，一个公开的接口，可能会因为多种多样的原因被废弃。

比如说，这个接口的设计是危险的，或者有了更新的、更好的替代接口。

不管是什么原因，废弃接口的使用者们都需要尽快迁移代码，转换到替代方案上来。

在 JDK 中，公开接口的废弃需要使用两种不同的机制，也就是“Deprecated” 注解（annotation）和“Deprecated”文档标记（JavaDoc tag）。

Deprecated 的注解会编译到类文件里，并且可以在运行时查验。

这就允许像 javac 这样的工具检测和标记已废弃接口的使用情况了。

Deprecated 文档标记用于描述废弃接口的文档中。

除了标记接口的废弃状态之外，一般情况下，还要描述废弃的原因和替代的方案。

下面的这段代码，就是使用 Java 注解和文档标记来废弃一个公开接口的例子。

public sealed abstract class Digest 
    /**
     * -- snipped
     *
     * @deprecated This method is not performance friendly. Use
     *             @link #digest(byte[], byte[]) instead.
     */
    @Deprecated
    public abstract byte[] digest(byte[] message);

    // snipped
    public void digest(byte[] message, byte[] digestValue) 
        // snipped

如果一段程序使用了废弃接口，编译的时候，就会提出警告。

但是，有很多编译环境的配置，把编译警告看作是编译错误。

为了解决这样的问题，JDK 还提供了“消除使用废弃接口的编译警告”的选项。也就是 SuppressWarnings 注解。

@SuppressWarnings("deprecation")
public static void main(String[] args) 
    try 
        Digest.of("SHA-256")
              .digest("Hello, world!".getBytes());
     catch (NoSuchAlgorithmException ex) 
        // ignore

公开接口的废弃机制，是在 JDK 1.5 的时候发布的。

这种机制像一座设计者和使用者之间的沟通桥梁，减轻了双方定义或者使用废弃接口的痛苦。

遗憾的是，直到现在，公开接口的废弃，依然是一个复杂、痛苦的过程。

一个公开的接口，从声明废弃，到彻底删除是一个漫长的过程。

在 JDK 中，还存在着大量废弃了 20 多年都无法删除的公开接口。为什么删除废弃的公开接口这么困难呢？

如果从废弃机制本身的角度来思考，下面几个问题延迟了废弃接口使用者的迁移意愿和努力。

第一个问题，也是最重要的问题，就是 SuppressWarnings 注解的使用。SuppressWarnings 注解的本意是消除编译警告，保持向后的编译兼容性。可是一旦编译警告消除，SuppressWarnings 注解也就抵消了 Deprecated 注解的功效。代码的维护者一旦使用了 SuppressWarnings 注解，就很难再有更合适的工具，让自己知道还在使用的废弃接口有哪些了。不知道，当然就不会有行动。
第二个问题，就是废弃接口的使用者并不担心使用废弃接口。虽然我们都知道不应该使用废弃的接口，但是因为一些人认为没有紧急迁移的必要性，也不急着制定代码迁移的时间表，所以倾向于先使用 SuppressWarnings 注解把编译警告消除了，以后再说迁移的事情。然后，就掉入了第一个问题的陷阱。
第三个问题，就是废弃接口的使用者并不知道接口废弃了多久。在接口使用者的眼里，废弃了十年，和废弃了一年的接口，没有什么区别。可是，在接口维护者的眼里，废弃了十年的接口，应该可以放心地删除了。然而，使用者并没有感知到这样的区别。没有感知，当然也就没有急迫感了。一旦一个接口被声明为废弃，它的问题也就再难进入接口维护者的任务列表里了。

这个接口的实现可能充满了风险和错误。于是局面就变成了，接口维护者难以删除废弃的接口，接口的使用者又不能获得必要的提示，这种情况实在有点尴尬。

二、改进的废弃

在 JDK 9 的接口废弃机制里有了重大的改进。第一个改进是添加了一个新的工具，jdeprscan。

有了这个工具，就可以扫描编译好的 Java 类或者包，看看有没有使用废弃的接口了。即使代码使用了 SuppressWarnings 注解，jdeprscan 的结果也不受影响。

这个工具解决了在阅读案例里提到的第一个问题。

如果使用第三方的类库，或者已经编译好的类库，发现对废弃接口的依赖关系很重要。如果将来废弃接口被删除，使用废弃接口的类库将不能正常运行。而 jdeprscan 允许我们在使用一个类库之前进行废弃依赖关系检查，提前做好风险的评估。
第二个改进是给 Deprecated 注解增加了一个“forRemoval”的属性。如果这个属性设置为“true"，那就表示这个废弃接口的删除已经提上日程了。两到三个版本之后，这个废弃的接口就会被删除。这样的改进，强调了代码迁移的紧急性，它给了使用者一个明确的提示。这个改进，解决了我们在阅读案例里提到的第二个问题。
第三个改进是给 Deprecated 注解增加了一个“since”的属性。这个属性会说明这个接口是在哪一个版本废弃的。如果我们发现一个接口已经废弃了三年以上，就要考虑尽最大努力进行代码迁移了。这样的改进，给了废弃接口的使用者一个时间上的概念，也方便开发者安排代码迁移的时间表。这个改进，解决了在阅读案例里提到的第三个问题。

下面的这段代码，就是一个使用了这两种属性的例子。

public sealed abstract class Digest 
    /**
     * -- snipped
     *
     * @deprecated This method is not performance friendly. Use
     *             @link #digest(byte[], byte[]) instead.
     */
    @Deprecated(since = "1.4", forRemoval = true)
    public abstract byte[] digest(byte[] message);

    // snipped
    public void digest(byte[] message, byte[] digestValue) 
        // snipped

如果在 Deprecated 注解里新加入“forRemoval”属性，并且设置为“true"，那么以前的 SuppressWarnings 就会失去效果。

要想消除掉编译警告，需要使用新的选项。

就像下面的例子这样。

@SuppressWarnings("removal")
public static void main(String[] args) 
    try 
        Digest.of("SHA-256")
              .digest("Hello, world!".getBytes());
     catch (NoSuchAlgorithmException ex) 
        // ignore