| RFC-0058：加入已淘汰的屬性 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 使用已淘汰的新屬性來指出類型 (列舉、結構體、聯集、使用宣告)、常數、方法或整個介面的淘汰。如要以最佳方式指定語言，請將這部分保留下來。 |
| 作者 | |
| 提交日期 (年/月) | 2018-09-10 |
| 審查日期 (年/月) | 2018-10-11 |
摘要
使用新的屬性 [Deprecated] 來指出類型 (列舉、結構、聯集、使用宣告)、常數、方法或整個介面的淘汰作業。如要以最佳方式指定語言，請將這部分保留下來。
與其他 RFC 的關係
這個 RFC 已由以下因素取代：
提振精神
我們有很多註解指出不應再使用類型、方法或介面。請按這裡或這裡查看範例。 我們制定標準來傳達淘汰訊息、在 JSON IR 中公開這項資訊，並在不同語言後端使用這項資訊，進而以目標語言將這些附註轉換成警告，輕鬆引導開發人員使用 API。
今日使用情形問卷調查
已使用「ack --type=fidl -i 'deprecated' -A 2 -B 2」完成問卷調查
- 使用方法時
- fuchsia.io/Ioctl
- fuchsia.tracelink/RegisterTraceProvider 已淘汰
- fuchsia.modular/GetAuthenticationContext
- fuchsia.modular/GetActiveLinks
- fuchsia.modular/重複
- fuchsia.modular.module/ 請改用 StartOngoingActivity
- fuchsia.mediaplayer/SetReaderSource
- fuchsia.ui.viewsv1/AddChild
- fuchsia.ui.viewsv1/RemoveChild
- fuchsia.ui.viewsv1/CreateView
- fuchsia.testing.runner/Fail
- fuchsia.netstack/GetNodeName
- fuchsia.netstack/SetRouteTable
- 欄位
- fuchsia.modular/CreateStory -- module_url 引數
- fuchsia.modular/CreateStoryWithInfo -- module_url 引數
- fuchsia.modular.intent/ json -> entity_reference
- 介面上
- fuchsia.simplecamera.SimpleCamera
- fuchsia.sys.ServiceProvider
- fuchsia.media.AudioOut
- fuchsia.media.AudioIn
設計
建議及記錄 [Deprecated] 屬性的用法。您可以視需要新增附註，說明淘汰項目和偏好的替代方案，例如：[Deprecated = "explanation"]。
FIDL 編譯器不會變更。
儘管我們可能希望針對使用已淘汰的類型或訊息 (尤其是各程式庫邊界) 顯示淘汰警告訊息，但我們選擇一開始的實作方式最少。之所以這麼做，是因為使用者想知道這些 [Deprecated] 屬性在實務中的使用方式，並避免日後需要編譯器的複雜性。
變更各種語言後端，詳情請參閱下一節：
在 Rust 中，視情況新增
#[deprecated]或#[deprecated(note = "explanation")]。在 Dart 中，視情況新增
@Deprecated。如有提供說明，也可以考慮新增自動註解。在 Go 中視情況新增註解
// Deprecated.或// Deprecated: explanation.。(請參閱三種建議的表單)。在 C++ 中，視情況新增
[[deprecated]]或[[deprecated("explanation")]]。
最後，我們想記錄這項功能。理想的做法是在 API 評分量表的「良好設計模式」下進行討論。
指定語言淘汰的相關規定
| FIDL | 以譯文語言顯示 |
|---|---|
| 類型別名 (例如使用 foo = bar;) | 沒有任何影響，目前類型別名僅涉及前端問題，不會在 JSON IR 中顯示。 |
| 並行聲明 | 在定義的常數上，例如當我們使用常數時加以警告。 |
| 訊息 (例如 struct、聯集、資料表) | 在代表 FIDL 訊息的頂層類型 (類別/結構) 上加註，也就是開發人員使用的類型。 |
| 欄位 (例如結構欄位、資料表欄位) | 在代表特定 FIDL 欄位的類型欄位中，和/或這個欄位的所有存取子方法 (例如 ClearXxx、SetXxx 等) |
| 方法、事件或介面 | 放置在與用戶端連接的物件/函式 (例如 Proxy) 上，但不放置在服務用戶端上的物件/函式上 (例如不在虛設常式上)；詳情請參閱下方的注意事項。 |
附註
我們可以引入 [DeprecatedForClients] 和 [DeprecatedForServices] 屬性來控制哪些端已淘汰，但在使用節目淘汰功能時，多半是為了通知消費者。
淘汰為錯誤
視建構設定和 pragma 而定，指定語言中的淘汰註解會引發錯誤。
例如在 Rust 中，#deprecated 屬性會發出警告。不過，這通常會與 Crate 層級 #![deny(warnings)] 結合，後者會將所有警告提高為錯誤。這會強制使用已淘汰函式、變數和方法的使用者在使用時指定 #allow(deprecated)。這個特定用途網站適當記錄了刻意使用已淘汰程式碼的意圖。
另一個範例是，Go 中針對淘汰警示的支援並不直接，而且需要轉向第三方工具，例如 staticcheck.io。
因此，FIDL 程式庫作者應瞭解，[Deprecated] 屬性引入是來源層級的破壞性變更。在大多數情況下，會需要程式庫使用者的部分新註解。
導入策略
兩種觀察：
- 每種語言後端都可獨立實作。
[Deprecated]屬性可在支援不同後端支援的各種 .fidl 檔案中導入。
建議策略是先將臨時註解轉換成這個提議的屬性，以便在各個 .fidl 檔案中使用 [Deprecated] 屬性。
在單獨的變更中，處理 Dart、Rust 和 C++，因為它們有部分指定語言支援。
針對 Go，我們建議在使用文件註解時實作這項變更。(尤其是由於淘汰通知必須正確融合文件註解，因此一般做法是包含文件註解、換行，以及淘汰通知)。
就說明文件而言，變更應在 .fidl 檔案中使用此屬性後，或在一個語言後端首次實作後立即生效。
說明文件與範例
在 API 評分量表的「良好設計模式」一節下方，新增「Deprecation」子區段。此外，請一併記錄這個屬性和其他資料。
回溯相容性
沒有影響。
效能
沒有影響。
安全性
沒有影響。
測試
測試會在每個後端程式碼第 代層級進行。
缺點、替代方案和未知
系統會評估本提案的實作費用，且可在每個語言後端逐一完成。此外，這項慣例已明確指出淘汰方式，並提供為現有 FIDL 檔案加上註解的指引。
我們也可以選擇不導入任何程式碼，也不提供任何淘汰指示的支援。如果不採取任何行動，我們便能避免在此時做出承諾，從而指出淘汰項目，尤其是在更多使用量之前。(快速夾克搜尋可產生 20 到 25 個地點的順序)。
我們也可能引進一個要淘汰的語言關鍵字，並將其做為文法的一部分。這看起來過於嚴苛，而且相當複雜，尤其是對於說明文件沒有語意含義的特徵而言。
先前的圖片和參考資料
能夠說明淘汰事宜和替代的方案，是多種程式設計語言的常見功能 (如上所述)。
在 protobuf 中，只有欄位才能淘汰：「如果設為 true，則代表該欄位已淘汰，且不應用於新程式碼。在大部分的語言中，這都沒有實際效果。在 Java 中，這會成為 @Deprecated 註解。日後，其他語言專用的程式碼產生器可能會針對欄位的存取子產生淘汰註解，這樣在編譯嘗試使用欄位的程式碼時，會產生警告。如果沒有任何人使用此欄位，而您想防止新使用者使用該欄位，請考慮將欄位宣告替換為保留的陳述式。」
Mojo 和 Thrift 似乎還沒有這類功能。
扁緩衝區，僅限欄位：「不要再產生這個欄位的存取子，程式碼應停止使用這項資料」。