Java Deprecated 注解

最后修改时间：2025 年 4 月 13 日

Java 中的 @Deprecated 注解标记了不应再使用的程序元素，表明它们已过时，并可能在未来的版本中被移除。已弃用的元素仍然可以运行，但应避免使用，因为继续使用可能会导致兼容性问题、意外行为或与现代替代方案相比效率低下。

当类、方法或字段被标记为已弃用时，Java 编译器会在每次使用它们时生成警告，提示开发人员迁移到推荐的替代方案。该注解在保持向后兼容性的同时，鼓励代码向改进的 API 演进方面发挥着关键作用。

Deprecated 注解基础

@Deprecated 注解是 java.lang 包的一部分，可以应用于各种程序元素，包括类、方法、字段和构造函数。开发人员可以使用两种形式：作为简单的标记，或使用提供有关其弃用的更多上下文的附加属性。

@Target(value={CONSTRUCTOR,FIELD,LOCAL_VARIABLE,METHOD,PACKAGE,PARAMETER,TYPE})
@Retention(value=RUNTIME)
public @interface Deprecated {
    String since() default "";
    boolean forRemoval() default false;
}

since 属性指定元素被弃用的版本，帮助开发人员跟踪其生命周期。 forRemoval 属性指示该元素是否计划在未来的版本中删除，允许开发人员相应地进行计划并在发生重大更改之前重构代码。

处理已弃用元素的最佳实践

为了确保可维护的和面向未来的代码，开发人员在使用已弃用元素时应遵循以下最佳实践

查看文档： 始终参考官方文档，了解已弃用 API 的推荐替代方案。
主动迁移： 避免在新代码中依赖已弃用的元素，并在可能的情况下更新现有实现。
必要时抑制警告： 仅在无法立即解决弃用的情况下使用 @SuppressWarnings("deprecation")。
监控 API 更改： 随时了解计划的删除，尤其是在升级到较新的 Java 版本时。

@Deprecated 注解可帮助开发人员从过时的功能过渡，同时确保平稳的应用程序升级并更好地遵守现代 Java 标准。

简单的弃用示例

此示例演示了在方法上使用 @Deprecated 注解的基本用法。当使用此方法时，编译器将生成警告。

Main.java

package com.zetcode;

class Calculator {
    /**
     * @deprecated This method is deprecated because it uses integer division.
     * Use {@link #divide(double, double)} instead.
     */
    @Deprecated
    public int divide(int a, int b) {
        return a / b;
    }
    
    public double divide(double a, double b) {
        return a / b;
    }
}

public class Main {

    public static void main(String[] args) {
        Calculator calc = new Calculator();
        // Generates compiler warning
        int result = calc.divide(10, 3);
        System.out.println("Deprecated method result: " + result);
        
        // Preferred alternative
        double preciseResult = calc.divide(10.0, 3.0);
        System.out.println("New method result: " + preciseResult);
    }
}

该示例显示了一个已弃用的整数除法方法，其中包含一个 Javadoc @deprecated 标记，解释了它被弃用的原因并建议了一个替代方案。新方法提供了更精确的浮点除法。

弃用与 since 和 forRemoval

此示例演示了如何使用 since 和 forRemoval 属性来提供有关弃用状态的更多信息。

Main.java

package com.zetcode;

class OldAPI {
    /**
     * @deprecated This field was deprecated in version 2.5 and will be removed
     * in a future release. Use {@link #NEW_CONSTANT} instead.
     */
    @Deprecated(since = "2.5", forRemoval = true)
    public static final String OLD_CONSTANT = "old";
    
    public static final String NEW_CONSTANT = "new";
}

public class Main {

    public static void main(String[] args) {
        // Generates stronger warning due to forRemoval=true
        System.out.println("Old constant: " + OldAPI.OLD_CONSTANT);
        
        // Preferred alternative
        System.out.println("New constant: " + OldAPI.NEW_CONSTANT);
    }
}

since 属性指示该字段何时被弃用，而 forRemoval=true 表示它将在未来的版本中被删除。这会生成更强的编译器警告，以鼓励立即迁移。

弃用整个类

此示例演示了如何弃用整个类并提供有关其替换的信息。

Main.java

package com.zetcode;

/**
 * @deprecated This class is deprecated as of version 3.0 because it uses
 * legacy encryption. Use {@link AESEncryptor} instead for better security.
 */
@Deprecated(since = "3.0")
class DESEncryptor {
    public String encrypt(String data) {
        // Legacy DES encryption logic
        return "DES:" + data;
    }
}

class AESEncryptor {
    public String encrypt(String data) {
        // Modern AES encryption logic
        return "AES:" + data;
    }
}

public class Main {

    public static void main(String[] args) {
        // Generates warning
        DESEncryptor oldEncryptor = new DESEncryptor();
        System.out.println(oldEncryptor.encrypt("secret"));
        
        // Preferred alternative
        AESEncryptor newEncryptor = new AESEncryptor();
        System.out.println(newEncryptor.encrypt("secret"));
    }
}

该示例显示了一个已弃用的加密类，并提供了一个建议的替代方案。 Javadoc 解释了该类被弃用的原因以及应该使用什么来代替它。类注解和 Javadoc 标记一起工作以传达弃用。

弃用构造函数

此示例演示了如何在提供创建对象的替代方法的同时弃用构造函数。

Main.java

package com.zetcode;

class Connection {
    private String url;
    private int timeout;
    
    /**
     * @deprecated This constructor is deprecated as of version 1.2 because
     * timeout should always be specified. Use {@link #Connection(String, int)}
     * or {@link #createDefault(String)} instead.
     */
    @Deprecated(since = "1.2")
    public Connection(String url) {
        this(url, 5000); // Default timeout
    }
    
    public Connection(String url, int timeout) {
        this.url = url;
        this.timeout = timeout;
    }
    
    public static Connection createDefault(String url) {
        return new Connection(url, 5000);
    }
}

public class Main {

    public static void main(String[] args) {
        // Generates warning
        Connection conn1 = new Connection("http://example.com");
        
        // Preferred alternatives
        Connection conn2 = new Connection("http://example.com", 3000);
        Connection conn3 = Connection.createDefault("http://example.com");
    }
}

该示例弃用了一个使用默认超时值的构造函数。提供了两种替代方法：具有显式超时的构造函数和一个工厂方法。这展示了如何在保持向后兼容性的同时引导用户采用更好的实践。

抑制弃用警告

此示例展示了当您必须使用已弃用的代码时（例如在迁移或测试期间）如何抑制弃用警告。

Main.java

package com.zetcode;

class LegacySystem {
    /**
     * @deprecated This method will be removed in version 5.0. Use newAPI()
     * instead.
     */
    @Deprecated(since = "4.0", forRemoval = true)
    public void oldAPI() {
        System.out.println("Running old API");
    }
    
    public void newAPI() {
        System.out.println("Running new API");
    }
}

public class Main {
    @SuppressWarnings("deprecation")
    public static void main(String[] args) {
        LegacySystem system = new LegacySystem();
        
        // No warning due to @SuppressWarnings
        system.oldAPI();
        
        // Preferred alternative
        system.newAPI();
        
        testLegacyFeatures();
    }
    
    // Method to test deprecated features
    @SuppressWarnings("deprecation")
    private static void testLegacyFeatures() {
        LegacySystem testSystem = new LegacySystem();
        testSystem.oldAPI(); // No warning in test code
    }
}

该示例使用 @SuppressWarnings("deprecation") 来在使用已弃用方法时消除警告。应该谨慎使用它，并且仅在必要时使用，并在注释中给出明确的理由。

接口中的弃用

此示例演示了如何弃用接口方法并提供默认实现来帮助迁移。

Main.java

package com.zetcode;

interface PaymentProcessor {
    /**
     * @deprecated As of version 2.0, use processPayment(amount, currency)
     * instead. This method assumes USD which is not suitable for international
     * payments.
     */
    @Deprecated(since = "2.0")
    default void processPayment(double amount) {
        processPayment(amount, "USD");
    }
    
    void processPayment(double amount, String currency);
}

class OnlinePayment implements PaymentProcessor {
    @Override
    public void processPayment(double amount, String currency) {
        System.out.printf("Processing %.2f %s payment%n", amount, currency);
    }
}

public class Main {

    public static void main(String[] args) {
        PaymentProcessor processor = new OnlinePayment();
        
        // Generates warning
        processor.processPayment(100.0);
        
        // Preferred alternative
        processor.processPayment(100.0, "EUR");
    }
}

该示例显示了接口中一个已弃用的默认方法，并提供了一个更好的替代方案。默认方法允许在鼓励迁移到较新版本的 API 的同时保持向后兼容性。

弃用枚举常量

此示例演示了如何在保持其他枚举常量处于活动状态的同时弃用特定的枚举常量。

Main.java

package com.zetcode;

enum Browser {
    /**
     * @deprecated Internet Explorer is no longer supported as of version 11.
     */
    @Deprecated(since = "2022")
    IE,
    CHROME,
    FIREFOX,
    EDGE
}

public class Main {

    public static void main(String[] args) {
        // Generates warning
        Browser deprecated = Browser.IE;
        System.out.println("Deprecated browser: " + deprecated);
        
        // Active browsers
        for (Browser browser : Browser.values()) {
            if (!browser.name().equals("IE")) {
                System.out.println("Supported browser: " + browser);
            }
        }
    }
}

该示例弃用了 IE 枚举常量，同时保持其他枚举常量处于活动状态。当逐步淘汰对枚举中特定选项的支持，同时保持枚举的其余部分时，此模式非常有用。

来源

Java Deprecated 注解文档

在本教程中，我们通过实际示例介绍了 Java @Deprecated 注解的各个方面。正确使用弃用有助于保持向后兼容性，同时引导用户采用更好的替代方案。

作者

我叫 Jan Bodnar，是一位经验丰富的专业程序员。我于 2007 年开始撰写编程文章，至今已撰写了 1,400 多篇文章和 8 本电子书。凭借超过 8 年的教学经验，我致力于分享我的知识并帮助他人掌握编程概念。

列出所有Java教程。