deprecated

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

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

第三方注釋

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

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

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

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

自定義注釋

如果由于其他任何原因未將庫與批注一起使用，則在編寫自己的自定義批注相對簡單時(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)成的支持。

僅評論

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

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

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

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

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

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

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

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

棄用是一種用于傳達(dá)有關(guān)API生命周期的信息的技術(shù)：鼓勵應(yīng)用程序從API遷移過來，阻止應(yīng)用程序形成對API的新依賴關(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ì)劃將其刪除。 為了使這種方法最有效，可能會寫成將forRemoval明確聲明為false，而不是依賴于其隱式默認(rèn)值。

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

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

deprecated

總結(jié)

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

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