Java中如何标记不推荐使用但暂不删除的公共方法？

方案1：调整@Deprecated注解属性适配SonarLint规则 #

Java 9 开始@Deprecated注解新增了forRemoval属性，显式设置为false即可明确告知工具该方法仅不推荐使用，不会在后续版本移除，完美解决SonarLint的提示问题：

/**
 * 通用配置读取方法，仅特殊场景下允许使用
 * @deprecated 普通业务场景请使用对应配置项的类型安全Getter，例如 {@link #getLogLevel()}
 */
@Deprecated(since = "1.0", forRemoval = false)
public String get(String key) {
    return values.get(key);
}

这个方案是成本最低的原生方案，不需要引入任何第三方依赖，也符合Java官方对@Deprecated的语义定义：该注解本身就支持标记「不推荐使用但暂时保留」的API，只是SonarLint的默认规则把它和「待移除API」绑定了，显式声明forRemoval = false就能解除这个误报。

方案2：使用第三方语义化注解 #

如果你的项目已经引入了JetBrains的注解包（常用来做可为空/非空标记），可以使用@ApiStatus系列注解更精准地标记语义：

import org.jetbrains.annotations.ApiStatus;

/**
 * 通用配置读取方法，仅框架内部特殊场景或扩展开发时允许使用
 * 普通业务场景请使用对应配置项的类型安全Getter，例如 {@link #getLogLevel()}
 */
@ApiStatus.Internal // 明确标注是内部API不建议外部业务使用
public String get(String key) {
    return values.get(key);
}

IDEA等工具会识别这个注解，在开发者调用时弹出对应的不建议使用的提示，语义比默认的@Deprecated更清晰。

方案3：API签名层面增加调用门槛（最高效的拦阻方式） #

如果希望从使用层面尽可能避免开发者误调用通用方法，可以给方法增加一个仅内部使用的标记参数，从语法层面提高调用成本：

// 先定义一个仅内部可见的标记类
public final class InternalAccessMarker {
    private InternalAccessMarker() {}
    public static final InternalAccessMarker INSTANCE = new InternalAccessMarker();
}

// 改造通用get方法
public String get(String key, InternalAccessMarker marker) {
    // 可选加校验，防止外部随便传null绕过
    if (marker != InternalAccessMarker.INSTANCE) {
        throw new UnsupportedOperationException("仅内部特殊场景允许调用通用get方法");
    }
    return values.get(key);
}

普通开发者如果要调用这个方法，必须传入标记类实例，而这个实例如果不对外暴露的话，业务侧根本无法正常调用，只有内部特殊场景可以合法调用，比单纯的注解标记拦截效果好得多。

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