RFC-0231：FIDL 版本管理取代語法

摘要

變更 FIDL 的 @available 屬性，以支援 replaced 引數。這與 removed 類似，但會驗證替代項目是否為相同版本的 added。

背景

RFC-0083：FIDL 版本管理導入了 @available 屬性，用於管理 FIDL API 版本。該設計的一項要求是允許所有可能的變更進行版本控管。換句話說，應該可以在單一 versioned.fidl 檔案中，將 v1.fidl 轉換為任意不同的 v2.fidl。只要多個元素沒有重疊的版本範圍，設計就能滿足這項需求，允許這些元素使用相同名稱。

舉例來說，請考慮在第 5 版的通訊協定 P 中新增 @discoverable 屬性。我們無法直接使用 @available 表示這項資訊，因為屬性無法放在其他屬性上。不過，我們可以改為執行下列操作：

@available(added=1, removed=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

這種移除元素並以相同版本重新新增的技術稱為「交換」。

提振精神

新增、淘汰及移除 API 的一般生命週期語法相當直覺。但交換模式則不然。這項功能在說明後就很容易理解，但屬於隱藏功能，需要說明才能瞭解。在上述範例中，您可能會認為 removed=5 真的表示第 5 版中已沒有通訊協定，尤其是當對應的 added=5 並非位於原始碼中相鄰的位置時。

區分取代和移除作業，也有助於淘汰舊版功能，並改用更通用的解決方案。這是另一項提案：RFC-0232：適用於多個 API 級別的 FIDL 繫結。

利害關係人

協助人員：abarth@google.com

審查者： hjfreyer@google.com、ianloic@google.com、ddorwin@google.com

諮詢對象：wez@google.com、sethladd@google.com、wilkinsonclay@google.com

社交化：在撰寫 RFC 前，我與 FIDL 團隊和平台版本控管工作群組討論了這個想法。

設計

• 導入名為 replaced 的新 @available 引數。這個方法與 removed 的行為相同，但驗證方式不同，詳情請見下文。除了 library 宣告之外，您可以在任何元素上使用這個屬性，取代 removed。

• 如果元素標示為 removed=N，請確認沒有其他標示為 added=N 的同名元素。

• 如果元素標示為 replaced=N，請驗證是否有其他同名元素標示為 added=N。

• 這項驗證僅適用於直接標示 removed 或 replaced 的元素，不適用於繼承引數的子項元素。

範例

在背景部分中，將 @discoverable 新增至第 5 版通訊協定的範例在新設計中如下所示：

@available(added=1, replaced=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

再舉一個例子，假設要取代含有成員的結構體，可以改用匿名型別：

@available(added=1, replaced=2)
struct Foo {
    bar @generated_name("Bar") table {};
};

@available(added=2)
struct Foo {
    baz string;
};

由於第一個 Foo 標示為 replaced=2，因此 fidlc 會驗證是否有另一個標示為 added=2 的 Foo。不過，它不會對子元素 bar 或其匿名型別 Bar 執行類似的驗證。

實作

1. 實作 replaced 引數，包括驗證。

2. 視情況將所有 FIDL 檔案改為使用 replaced，而非 removed。

3. 導入新的 removed 驗證。如果 (2) 錯過任何內容，CQ 就會失敗。

效能

這項提案不會影響成效。

人體工學

這項提案直接在語言中支援交換模式，讓模式更符合人體工學。

回溯相容性

這項提案不會影響回溯相容性。

安全性考量

這項提案不會影響安全性。

隱私權注意事項

這項提案不會影響隱私權。

測試

如要測試新行為，必須更新下列檔案：

• tools/fidl/fidlc/tests/availability_interleaving_tests.cc
• tools/fidl/fidlc/tests/decomposition_tests.cc
• tools/fidl/fidlc/tests/versioning_tests.cc
• tools/fidl/fidlc/tests/versioning_types_tests.cc

說明文件

必須更新下列頁面，記錄 replaced：

• FIDL 屬性
• FIDL 版本管理
• Fuchsia API 演進指南

此外，也應移除「交換」一詞，改用「更換」。

fidldoc 工具目前會針對單一 API 級別的 JSON IR 運作，因此不會看到 removed 引數，也不會看到 replaced (https://fxbug.dev/42084086)。修正後，請更新 fidldoc，清楚指出項目是取代而非移除。

缺點、替代方案和未知事項

替代方案：重新新增引數

這項提案導入 replaced 引數，可清楚指出元素是遭到取代而非移除。可避免「我以為無法使用這個 API，因為系統顯示 removed=5，而我們的目標是 6」的情況。

同樣地，我們可以導入 re_added 引數，說明元素是新增為替代項目，還是首次新增。這樣一來，使用者就不會遇到「我以為還無法使用這個 API，因為系統顯示 added=6，而我們的目標是 5」的情況。

我拒絕這項替代方案的原因如下：

• 我認為第一種情況比第二種情況更重要。

• 「re_added」這個名稱不盡理想，但我找不到更好的名稱。

• 即使沒有這個屬性，fidldoc 仍可推斷元素是否為首次顯示。added

既有技術和參考資料

我在 2021 年開發 FIDL 版本控管時，曾在名為「FIDL versioning: Swapping elements」的內部文件中討論過類似的想法。

這項提案與 FIDL 版本控管的設計息息相關，據我所知，目前沒有針對這個問題的先前技術。