如何在java中将方法标记为不鼓励？

Posted 2023-02-21

【中文标题】如何在java中将方法标记为不鼓励？

【英文标题】：How can I mark a method as discouraged in java?

【发布时间】：2021-12-07 03:24:47

【问题描述】：

我正在编写一个 Config 类，它读取文件并将配置参数作为 Map 提供。 参数可以通过conf.get("LogLevel")或conf.getLogLevel()访问。

第一个函数只是从映射中读取并返回值（可以是null 或无效），而第二个函数将值转换为 LogLevel 并在没有给出有效值时返回默认值。

因此，我想劝阻程序员不要使用一般的get()，但是在某些特殊情况下，这种方法很有用，所以我不能让它受到保护。 现在我使用@Deprecated，但我认为这不是一个好的解决方案，因为它只是对将来会被删除的方法的修改。 （如果我错了，请纠正我，这就是 SonarLint 告诉我的关于 @Deprecated 注释的内容）

/**
 * @Deprecated When possible, use the key-specific getter instead
 */
public String get(String key) 
    return values.get(key);


public int getLogLevel() 
    return Log.getLogLevel(values.get(LOG_LEVEL), Log.getLogLevel(defaultValues.get(LOG_LEVEL)));

【问题讨论】：

定义您所说的“好的解决方案”是什么意思，它解释了为什么明确提供的注释不符合条件。

你也可以在你的 JavaDoc 中写 non-API 这样的东西来告诉人们它不是供公众使用的。

也许你可以利用 javadoc 标签@apiNote

【参考方案1】：

好吧，如果@Deprecated 不是解决方案，那么您只有一个选择。将说明该用法“不鼓励”（特殊情况除外）的消息放入 javadocs ...并希望人们将阅读 javadocs。

定义您自己的自定义注释将无济于事，因为您无法让您的用户使用能够识别它的注释处理器。

同样，您不能通过针对 FindBugs、PMD、Sonar 等的自定义规则来做到这一点，因为这需要您的用户自定义他们对这些产品的安装。

（虽然......如果这是一个内部产品并且您的所有用户都使用公共 CI 服务器......您可能会在 CI 服务器中进行检查。这取决于您是否可以定义自定义规则，可靠地区分一般“不鼓励”用例和特殊用例。这还需要让你的同事相信这是个好主意。）

---

在我看来，@Deprecated 标签会比以上所有标签都好。对于特殊情况，鼓励大家慎重在需要使用的情况下添加@SuppressWarning("deprecation")。

我认为这不是一个好的解决方案，因为它仅适用于将来将被删除的方法。

这是不正确的。未来可能的删除只是@Deprecatedjavadoc（Java 11 版本）中列出的弃用原因之一。列出的其他原因有：

“标记元素的使用可能会导致错误”， “它可能会在未来的版本中进行不兼容的更改 [...]”， “它已被更新的、通常更可取的替代品取代”，或 “它已过时”。

请注意，这些被列为示例原因...这意味着您可以出于其他原因弃用。

这也与旧的“何时弃用”指南 here 一致。

IMO，您的“气馁”情况已涵盖在内。