logo标签列表

如何将Java方法标记为过时或废弃？

javadeprecated
334

我希望将我的某个方法“弃用” = 不再使用。

但我仍希望在我的API中保留它。我只想向使用该方法的任何人显示“警告”。

我该如何实现这一目标？

10
你是否考虑过使用“@Deprecrated”？ - templatetypedef
28
是的，但我不知道它...这就是为什么我在问这个问题 :) - Pavel Janicek
1
请参阅http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecation.html。 - Raedwald
5
评论不是回答的地方！ - mattumotu
8个回答
653

在方法上使用@Deprecated。
不要忘记添加@deprecated Javadoc标签：

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}
2
如何链接外部库？ 例如： com.hello.api.PublicController#new - Faizan Kazi
@LinuxLars 完全同意！Java 9添加了一些属性，开始认真考虑弃用，但添加另一个默认值为 "" 的属性 reason 不会有害。 - asgs
5
我希望@Deprecated注释中能够添加@deprecated消息（一个地方修复所有问题）... - U. Windl
在接口/实现场景下应该怎么做？在Java接口中也将方法设置为废弃的吗？ - JBStonehenge
95

请同时使用@Deprecated注解和@deprecatedJavaDoc标签。

@deprecated JavaDoc标签用于文档记录目的。

@Deprecated注解指示编译器该方法已弃用。以下是Sun/Oracle的相关文档：

使用@Deprecated注解来弃用类、方法或字段，确保所有编译器在代码使用该程序元素时都会发出警告。相比之下，不能保证所有编译器都会基于@deprecated Javadoc标签发出警告，尽管Sun编译器目前可以这样做。其他编译器可能不会发出此类警告。因此，使用@Deprecated注解生成警告比依赖@deprecated Javadoc标签更具可移植性。

您可以在何时如何弃用API中找到完整的文档。

1
并不完全正确。 无论是 javadoc 还是注解，都会告诉编译器该方法已过时。 - Bohemian
18
@Bohemian 实际上这并不完全正确。注释在Java语言规范的第9.6.1.6节中进行了定义（http://java.sun.com/docs/books/jls/third_edition/html/interfaces.html#9.6.1.6），而javadoc标记没有定义。因此，注释是语言的一部分。如果您决定编写自己的Java编译器，可以忽略javadoc标记，但必须识别注释。 - ShaMan-H_Fel
@ShaMan-H_Fel 我相信Javadoc模型也是可行的。因为在Java 5之前，这是唯一的选择，而且它确实起作用。当您使用@deprecated Javadoc标记（在Java 4-中）标记方法时，编译器会将该方法（类、字段）标记为已弃用，并且IDE会显示警告，即使没有源代码也是如此。 - Amir Pashazadeh
56

由于缺少一些次要解释

可以像这样在方法上使用@Deprecated注释

 /**
 * @param basePrice
 * 
 * @deprecated  reason this method is deprecated <br/>
 *              {will be removed in next version} <br/>
 *              use {@link #setPurchasePrice()} instead like this: 
 * 
 * 
 * <blockquote><pre>
 * getProduct().setPurchasePrice(200) 
 * </pre></blockquote>
 * 
 */
@Deprecated
public void setBaseprice(int basePrice) {
}

请详细解释：

  1. 为什么这种方法不再推荐使用，在使用它时会出现什么问题。如果有相关讨论，请提供链接。（为了易读性，请使用<br/>分隔行）
  2. 何时将其移除。（告知用户，如果他们决定坚持旧的方式，可以依赖此方法的时间有多长）
  3. 提供解决方案或指向你所推荐的方法的链接 {@link #setPurchasePrice()}
应该使用 <br/> 而不是 </br>，对吗？ - argh1969
@argh1969，没错！我不记得当时从哪里得到的模板了。但我可以确认两个版本都可以工作。虽然我正在编辑以符合标准。 - azerafati
41
有两件事情你可以做：
  1. 将 @Deprecated 注解添加到该方法中，以及
  2. 在该方法的 javadoc 中添加一个 @deprecated 标签
应该同时执行这两个步骤！ 引用关于此主题的Java文档的话：

从 J2SE 5.0 开始，您可以使用 @Deprecated 注解来弃用类、方法或字段。另外，您可以使用 @deprecated Javadoc 标签告诉开发人员应该使用什么代替。

使用注解会导致 Java 编译器在使用被弃用的类、方法或字段时生成警告。如果已弃用的编译单元使用了被弃用的类、方法或字段，则编译器会抑制弃用警告。这使得您可以构建遗留 API 而不会产生警告。

强烈建议您使用 Javadoc 的 @deprecated 标签，并提供适当的注释来说明如何使用新的 API。这样可以确保开发人员有一个可行的迁移路径，从旧的 API 过渡到新的 API。

9

使用 注解 @Deprecated 标记你的方法，并且你还应该在 javadocs 中提到它。

链接现在已经失效。 - Yetti99
3

请看一下@Deprecated注解。

1
除了在方法上使用@Deprecated注解外，还要包含一个消息，说明为什么该方法被弃用以及可以使用的替代选项。
 /**
 * @deprecated
 * explain here why the method was deprecated, suggest alternate option to 
 * use
 */

示例消息
Deprecated, for removal: This API element is subject to removal in a future version. since 3.0.0 in favor of bstractCompositeHealthContributorConfiguration(Function)
0
你必须给这个服务加上注释 @Deprecated
这个回答是重复的，没有添加任何新内容。请不要发表回答，除非你确实有新的贡献。你可以通过点赞来支持原始回答。 - undefined
非常感谢，我是新手，还没有掌握所有的设置。非常感谢。 - undefined
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接