我偶爾遇到一種情況，我需要引入新的API或構造以供其他人試用，但是我知道在使用某些API后，它可能會根據其他人的反饋而改變。 在這種情況下，我想以某種方式注釋該構造，以警告其他開發人員此新添加的構造的暫定性。 在這些情況下，我考慮了幾種選擇。

• 使用第三方注釋，例如Guava的@Beta注釋。
• 開發自定義注釋。
• 僅使用注釋/ Javadoc。
• 將@Deprecated注釋與Javadoc @deprecated標記一起使用。

第三方注釋

Guava的@Beta注釋的Javadoc文檔指出：

表示在將來的發行版中，公共API（公共類，方法或字段）將遭受不兼容的更改，甚至被刪除。 帶有此注釋的API不受其包含庫所作的任何兼容性保證。 請注意，此批注的存在并不表示所討論的API的質量或性能，僅表示它不是“凍結的” API。

對@Beta用法的這種解釋似乎意味著這非常適合于可能被刪除的“新”結構。 我在博客文章“ 兩個普遍有用的番石榴注釋 ”中討論了更多有關此注釋的內容。

使用第三方庫的批注時的其他注意事項是，第三方庫必須包含在一個人的類路徑中，并且在最流行的Java IDE中通常不存在即開即用的支持以指示對該構造的特殊處理帶有注釋的注釋。

自定義注釋

如果由于其他任何原因未將庫與批注一起使用，則在編寫自己的自定義批注相對簡單時，僅為批注添加新的庫依賴項似乎有點繁重。 之前，我已經寫過有關編寫自定義@Unfinished批注的文章，該帖子還討論了如何在NetBeans 8.0.2和IntelliJ IDEA 14.0.3中為該自定義批注創建相應的自定義IDE檢查。

以下代碼清單提供了一個可用于此目的的自定義注釋的示例。

@預覽注釋

package dustin.examples.annotations;import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target;@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Preview {/*** Anticipated release in which Preview status will no longer apply.** @return Anticipated release of feature*/String transition() default "";/*** Version in which this preview feature was introduced.** @return Release in which this preview feature was introduced.*/String since() default "";/*** Reasons this construct is considered "preview."** @return Reasons this construct is considered preview.*/String[] reasons() default {}; }

自定義注釋在流行的Java IDE中缺少任何現成的支持。

僅評論

不一定需要使用注釋，簡單的注釋（Javadoc或其他方式）可以解釋特定的構造是初步的，可能會消失。 但是，就交流意圖而言，注釋在許多方面都比注釋弱。 使用IDE或其他工具解析注釋比處理注釋要困難得多。

@Deprecated批注和@deprecated Javadoc標記

可以使用@Deprecated對具有標準注釋的IDE，工具和腳本可以輕松處理的不贊成使用的結構進行注釋。 不幸的是， @Deprecated注釋從未得到我希望得到的全部支持，因為我希望它能更具體地說明為什么在決定讓JDK 9增強@Deprecated變得不那么雄心勃勃時不贊成使用某些東西。 Javadoc @deprecated標記可用于記錄棄用實際上是針對可能會消失但也不會消失的“新”構造的。 如果決定保留“預覽”結構，則可以刪除@Deprecated批注和@deprecated Javadoc標記。

盡管@Deprecated批注和@deprecated Javadoc標記從包括內置IDE支持和大多數Java開發人員意識的標準中受益，但使用這些標記來標記可能會消失的新結構仍然有些不合適。可能會黏附。 文檔“ 如何以及何時不推薦使用API ”的“ 何時不推薦使用 ”部分指出：“在設計API時，請仔細考慮它是否會取代舊的API。” 它進一步列出了棄用的三個原因，即“不安全，有錯誤或效率低下”，“在將來的版本中消失”和“鼓勵不良的編碼習慣”。

我并不是唯一認為“棄用”標記可能會被刪除或不應使用的內容的人。 NicolasFr?nkel概述了Java中的功能生命周期，并解釋說Java中的棄用是“對每個人的大膽而明確的聲明，至少在當前形式下，功能版本沒有未來。”

Alex Buckley在jdk-dev郵件列表消息“ JEP 12：處理支持預覽功能的標準API ”中寫道：

我們想使用“棄用棄用”作為標記“此API與預覽功能緊密相連”的方式。 如果預覽功能成為永久功能，則將刪除棄用項。 從終端棄用到不棄用的轉變是新穎的，但并不瘋狂-棄用具有多種含義，并且其在JDK中的歷史用法對于任何事情都不是很好的指南。

Buckley還引用了JEP 277 （“增強的棄用”）中有關棄用機制的使用的一段內容（我強調了Buckley強調的相同部分）：

棄用是一種用于傳達有關API生命周期的信息的技術：鼓勵應用程序從API遷移過來，阻止應用程序對API形成新的依賴關系，并告知開發人員繼續依賴API的風險 。

JDK 9引入的 “增強型” @Deprecated注釋可以通過其新添加的“ since ”和“ forRemoval ”元素在這種情況下有所幫助（Buckley稱之為“出生時棄用棄用”）。 指定@Deprecated注釋的forRemoval()為false ，并指定其since為同一版本的Javadoc @since標記可以幫助開發者看到，構造從一開始棄用目前尚無計劃將其刪除。 為了使這種方法最有效，可能會寫成將forRemoval明確聲明為false，而不是依賴于其隱式默認值。

可能我們的Java開發人員將需要開始考慮@Deprecated和@deprecated與過去有所不同。 盡管@Deprecated批注和@deprecated Javadoc標記仍“通知”我們對已注釋/描述的結構的“持續依賴的風險”，但認為這樣的結構將來必定會消失是不正確的。 如果我們在已棄用的JDK構造中習慣了這種替代含義，那么我們將更有可能考慮將相同的方法與我們自己新近添加但仍具有試驗性的功能一起使用。

翻譯自: https://www.javacodegeeks.com/2018/03/forward-looking-with-javas-deprecated.html

總結

以上是生活随笔為你收集整理的使用Java的@Deprecated前瞻的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。