如何使用DeprecationLevel.ERROR？库类弃用升级的技术咨询

刚好处理过类似的类库渐进式弃用场景，来给你一步步讲清楚DeprecationLevel.ERROR的用法，完全适配你要的「先警告、后严格限制、且保持二进制兼容」的需求：

DeprecationLevel.ERROR的核心价值就是：编译阶段阻止新代码使用目标类，但不删除任何代码，因此已编译的二进制文件（比如旧版本编译的程序）依然能正常调用该类——完美契合你不删代码、保兼容的要求。

第一步：先给用户缓冲期（警告级弃用） #

首先用默认的警告级别弃用，给使用者足够时间迁移代码。这里要明确标注弃用的版本、原因，以及替代方案：

/**
 * @deprecated 此类因自引用设计存在潜在风险，将在后续版本升级为编译错误。请使用 {@link AlternativeClass} 替代。
 * @since 1.5
 */
@Deprecated(since = "1.5", forRemoval = false, level = DeprecationLevel.WARNING)
public class SelfReferencingClass {
    // 自引用逻辑完全保留
    private SelfReferencingClass parent;

    public SelfReferencingClass() {}

    public void setParent(SelfReferencingClass parent) {
        this.parent = parent;
    }
}

这个阶段，用户使用该类时只会收到编译器警告，但代码能正常编译运行，不会影响现有业务。

第二步：升级为ERROR级别（严格限制新使用） #

经过缓冲期后，就可以把弃用级别提升为ERROR，此时新代码编译会直接报错，但旧代码的二进制运行不受任何影响：

/**
 * @deprecated 此类因自引用设计存在潜在风险，已禁止新代码使用。请使用 {@link AlternativeClass} 替代。
 * 已编译的旧代码仍可正常运行，无需修改。
 * @since 2.0
 */
@Deprecated(since = "2.0", forRemoval = false, level = DeprecationLevel.ERROR)
public class SelfReferencingClass {
    // 代码完全保留，不做任何删除或修改
    private SelfReferencingClass parent;

    public SelfReferencingClass() {}

    public void setParent(SelfReferencingClass parent) {
        this.parent = parent;
    }
}

关键细节说明： #

• 必须设置forRemoval = false：如果设为true，部分静态分析工具或构建工具会将其标记为「待删除类」，而你的目标是永久保留代码保兼容，所以这个参数一定要注意。
• 自引用类的特殊性：类内部的自引用逻辑完全不受影响，因为DeprecationLevel.ERROR只限制外部代码的新引用，类自身的结构和方法调用依然正常编译运行。
• 二进制兼容性验证：你可以用旧版本类库编译一个使用该类的程序，替换成新版本类库后运行，会发现程序完全正常——因为字节码没有任何变化，只是编译阶段的规则变严了。

额外建议 #

一定要在类库的Release Notes、文档中明确告知使用者弃用的节奏：比如1.5版本开始警告，2.0版本升级为编译错误，且旧代码无需修改。这样能避免使用者的困惑，也能引导他们及时迁移到替代方案。

内容的提问来源于stack exchange，提问作者mkobit