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

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

第三方注釋

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

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

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

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

自定義注釋

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

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

@預(yù)覽注釋

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中缺少任何現(xiàn)成的支持。

僅評(píng)論

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

@Deprecated批注和@deprecated Javadoc標(biāo)記

可以使用@Deprecated對(duì)具有標(biāo)準(zhǔn)注釋的IDE，工具和腳本可以輕松處理的不贊成使用的結(jié)構(gòu)進(jìn)行注釋。 不幸的是， @Deprecated注釋從未得到我希望得到的全部支持，因?yàn)槲蚁Ｍ芨唧w地說明為什么在決定讓JDK 9增強(qiáng)@Deprecated變得不那么雄心勃勃時(shí)不贊成使用某些東西。 Javadoc @deprecated標(biāo)記可用于記錄棄用實(shí)際上是針對(duì)可能會(huì)消失但也不會(huì)消失的“新”構(gòu)造的。 如果決定保留“預(yù)覽”結(jié)構(gòu)，則可以刪除@Deprecated批注和@deprecated Javadoc標(biāo)記。

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

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

Alex Buckley在jdk-dev郵件列表消息“ JEP 12：處理支持預(yù)覽功能的標(biāo)準(zhǔn)API ”中寫道：

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

Buckley還引用了JEP 277 （“增強(qiáng)的棄用”）中有關(guān)棄用機(jī)制的使用的一段內(nèi)容（我強(qiáng)調(diào)了Buckley強(qiáng)調(diào)的相同部分）：

棄用是一種用于傳達(dá)有關(guān)API生命周期的信息的技術(shù)：鼓勵(lì)應(yīng)用程序從API遷移過來，阻止應(yīng)用程序?qū)PI形成新的依賴關(guān)系，并告知開發(fā)人員繼續(xù)依賴API的風(fēng)險(xiǎn) 。

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

可能我們的Java開發(fā)人員將需要開始考慮@Deprecated和@deprecated與過去有所不同。 盡管@Deprecated批注和@deprecated Javadoc標(biāo)記仍“通知”我們對(duì)已注釋/描述的結(jié)構(gòu)的“持續(xù)依賴的風(fēng)險(xiǎn)”，但認(rèn)為這樣的結(jié)構(gòu)將來必定會(huì)消失是不正確的。 如果我們?cè)谝褩売玫腏DK構(gòu)造中習(xí)慣了這種替代含義，那么我們將更有可能考慮將相同的方法與我們自己新近添加但仍具有試驗(yàn)性的功能一起使用。

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。