如何用@Deprecated注解标记移除版本及多并行版本适配问题

一、标注移除版本的规范方式 #

JDK原生的@Deprecated注解并没有专门的属性用来指定移除版本，不过有两种比较实用的规范做法：

• Javadoc + 原生注解组合：这是最通用且IDE原生支持的方式。在Javadoc的@deprecated标签里明确说明移除版本，同时配合@Deprecated(forRemoval = true)标记该元素会被移除。示例：

/**
 * 此类已废弃，将在4.5.0版本中被移除
 * @deprecated since 4.3.0，计划于4.5.0版本移除
 */
@Deprecated(since = "4.3.0", forRemoval = true)
public class LegacyClass {
    // 类实现
}

这样既符合Javadoc规范，IDE（比如IntelliJ、Eclipse）也会根据forRemoval = true显示强烈的移除提示，同时Javadoc里的移除版本信息也能被所有开发者清晰看到。

• 自定义补充注解：如果团队需要更结构化的版本信息，可以自定义一个注解来标记移除版本，比如：

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
public @interface DeprecatedRemovalVersion {
    String value();
}

然后和原生注解配合使用：

@Deprecated(since = "4.3.0", forRemoval = true)
@DeprecatedRemovalVersion("4.5.0")
public class LegacyClass {
    // ...
}

不过这种方式需要团队统一配置IDE（比如通过自定义检查规则）才能让IDE识别并提示，通用性不如第一种方式。

二、多并行分支下的版本识别，摆脱纯注释依赖 #

针对多分支（4.3、4.2、4.1）各自废弃起始版本不同的情况，原生@Deprecated的since属性就是专门用来解决这个问题的：

• 每个分支单独维护since属性的值：比如4.3分支的代码里写@Deprecated(since = "4.3.0")，4.2分支写@Deprecated(since = "4.2.0")，IDE会直接读取当前代码中的since值来显示废弃起始版本的提示，完全不需要依赖注释。
• 如果觉得原生注解的信息拆分不够明确，也可以自定义@DeprecatedSince注解来单独标记废弃起始版本，配合@Deprecated(forRemoval = true)和自定义的移除版本注解使用。但同样，这种方式需要团队统一IDE配置才能生效，而原生since属性是IDE原生支持的，不需要额外配置，更省心。

整体来看，优先用原生@Deprecated配合Javadoc的方式，既能满足IDE识别需求，又能保证跨团队、跨环境的通用性。

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