RFC-0165：SDK 類別

RFC-0165：SDK 類別
狀態已接受
區域
  • 開發人員
說明

SDK 原子有描述成熟度和目標對象的類別。
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2022-05-13
審查日期 (年-月-日)2022-05-31

編輯此 RFC

編輯 RFC 中繼資料

摘要

每個 SDK Atom 都有一個類別，定義哪些類型的 SDK 使用者可以看到 Atom。隨著 SDK Atom 的成熟，我們可以提高其能見度，也就是提高穩定性保證。

提振精神

Fuchsia 是透過結合許多不同的元件而建構而成，這些元件會使用 FIDL 中定義的通訊協定進行互動。Fuchsia 專案的元件會使用與第三方撰寫的元件與 Fuchsia 平台互動相同的機制互相連結。因此，我們採用統一機制，可用於開發 Fuchsia 和為 Fuchsia 開發，這對我們來說是一大福音。

最簡單的方法是將所有 FIDL 定義放入 Fuchsia SDK，然後讓所有開發人員在開發元件時使用相同的 FIDL 定義。不過，這種做法會失效，因為設計 API 時常見到一種矛盾：API 設計人員需要能夠重複執行設計，而 API 消費者則需要穩定性，才能在 API 上建構。

本文件說明 SDK 類別，這是平衡這些疑慮的現有機制。SDK 類別早於 RFC 程序。本文件僅記錄現有機制。

SDK 類別並非 Fuchsia 用來解決這項問題的唯一機制。舉例來說，Fuchsia 也會透過能力轉送限制元件可依賴的 FIDL 通訊協定。這些機制互補，因為如果沒有能力轉送功能，元件作者可能會傾向於建立內部 FIDL 定義的本機副本，而不是等待將這些定義新增至 SDK。同樣地，如果沒有 SDK 類別，元件作者可以開始依賴內部 FIDL 通訊協定，在自己的元件之間進行通訊。

相關人員

誰會受到這項 RFC 是否通過的影響？(此為選用部分，但建議您填寫)。

協助人員：

  • neelsa@google.com

審查者：

  • dschuyler@google.com
  • jamesr@google.com
  • jeremymanson@google.com
  • neelsa@google.com
  • sebmarchand@google.com
  • sethladd@google.com

社會化：

由於機制已完全實作，因此本 RFC 略過了社會化階段。

定義

SDK Atom 是可納入 SDK 的檔案集合。Fuchsia 代表使用 GN 中的 sdk_atom 範本的 SDK Atom。

SDK 目標是用於建立 SDK 的建構目標。例如，//sdk:core 是建立 Core SDK 的建構目標的 GN 標籤。這些目標可稱為 IDK 目標，因為它們會為 IDK 建立 JSON 中繼資料。SDK 製作管道的後期階段會使用這項 JSON 中繼資料產生完全整合的 Fuchsia SDK (例如，使用 Bazel 等建構系統)。

設計

FIDL 程式庫是 SDK Atom 的其中一種範例，但也有其他類型的 SDK Atom，包括 C++ 用戶端程式庫、文件和工具。SDK 類別適用於所有類型的 SDK Atom，但本文件會使用 FIDL 程式庫做為執行範例。

SDK 類別會辨識不同 API 使用者的需求，並平衡 API 的迭代與穩定性需求。與 API 設計人員「較為接近」的 API 使用者，通常不需要太在意穩定性，而且通常是第一批向 API 設計人員提供實作意見回饋的客戶。

每個 SDK Atom 都會附註 SDK 類別，定義哪些 SDK 消費者可以依附 SDK Atom。舉例來說，如果 fuchsia.foo FIDL 程式庫的 SDK 類別為 internal，表示只有 Fuchsia 專案中的 SDK 使用者可以依附 fuchsia.foo。如果有人想要變更 fuchsia.foo，就有可能會導致 Fuchsia 專案中的消費者無法運作，但不會導致其他專案中的消費者無法運作。

舉另一個例子來說，假設 fuchsia.bar FIDL 程式庫的 SDK 類別為 partner，這表示 fuchsia.bar 可在 Fuchsia 專案中使用，也可以由與 Fuchsia 專案合作的 SDK 消費者1 使用。變更 fuchsia.bar 時，會導致消費者發生問題的風險更高，因為這可能會導致依賴 fuchsia.bar 的合作夥伴發生問題。

最後，請考慮 fuchsia.qux FIDL 程式庫，其 SDK 類別為 public，表示 fuchsia.qux 可供一般大眾使用。變更 fuchsia.qux 風險極高，因為一般大眾開發的軟體集合可能沒有限制，也無法得知。

除了定義同心圓不斷增加的 API 使用者集合，SDK 類別也會定義不斷增加的穩定性視窗。舉例來說，fuchsia.foo 可能會在一天內大幅變動，因為 internal 類別會限制 Fuchsia 專案本身的曝光率。變更 fuchsia.foo 的使用者可以同時變更所有用戶端和伺服器，這表示 API 所需的穩定性視窗非常小，甚至為零。

相較之下，Fuchsia 與合作夥伴專案簽訂的協議中，包含了相容性視窗的預期值。舉例來說，我們目前與合作夥伴達成協議，將維持六週的相容性時限，但這個時限可能會在即將發布的 RFC 中有所變動。這項協議表示 fuchsia.bar 在一天內的變化幅度不會太大。相反地，我們需要以可維持相容性視窗的方式，逐步變更 fuchsia.bar。

目前，Fuchsia 沒有任何 SDK Atom 的 SDK 類別為 public，這表示 Fuchsia 並未承諾支援使用其 API 的一般大眾。不過，Fuchsia 專案將在某個時間點開始支援一般大眾使用其 API。屆時，Fuchsia 專案需要為這些 API 定義相容性時間窗，這可能會比 partner API 的相容性時間窗還長。

一般 SDK Atom 的生命週期會從 internal SDK 類別開始。在某個時間點，API 委員會可能會將 SDK Atom 升級至 partner SDK 類別，通常是在合作夥伴需要存取 Atom 中包含的 API 時。在未來某個時間點，當 Fuchsia 擁有非空的 public SDK 類別時，SDK Atom 也能從 partner 類別升級至 public 類別。部分 SDK Atom 可能會無限期保留在 internal SDK 類別中。其他人可能會升級到 partner，但不會升級到 public。

這個生命週期目前尚未完成，因為生命週期不涵蓋 SDK Atom 的淘汰和移除作業。舉例來說，我們可能需要為 SDK Atom 新增 historical 類別，因為這些 Atom 目前無法使用，但仍具有歷史價值。對現有模型的這類擴充功能超出本 RFC 的討論範圍。

請注意，此機制可與 @available 機制互補，用於平台版本管理。@available 機制會記錄 FIDL API 變更的時間和方式。SDK 類別機制會決定 API 設計人員可以多快進行變更的政策。

實作

我們已在 用於建構 SDK 的 GN 規則中實作 SDK 類別。每個 SDK Atom 都有一個 category 參數，其中包含下列其中一個值：

  • excluded：SDK 可能未包含 Atom；
  • experimental：(這個 SDK 類別沒有太大意義)；
  • internal：可在 Fuchsia 平台來源樹狀結構中使用；
  • cts：可用於 Fuchsia 的相容性測試；
  • partner：部分合作夥伴可使用；
  • public：一般大眾可使用。

這些類別會形成排序清單，目標對象數量會逐漸增加。舉例來說，public 類別中的 SDK Atom 必須提供給特定合作夥伴，因為 public 在這個清單中位於 partner 之後。

experimental 類別不太合理，因為我們有更好的機制 (例如GN visibility) 來控制 Fuchsia 平台來源樹狀結構中的程式碼用途。這個類別可能很快就會移除。

每個 SDK 目標也都有 category 參數，用於定義 SDK 運送給哪些消費者。建構系統會強制執行 SDK 目標中包含的所有項目，都具有適合該目標對象的 SDK 類別。舉例來說，partner 的 SDK 可以包含已授權供 public 使用的 SDK Atom (因為 public 在上述清單中位於 partner 之後)，但不能包含僅供 internal 使用而授權的 SDK Atom (因為 internal 在上述清單中位於 partner 之前)。

excluded SDK 類別可用於二次檢查，避免特定目標納入 SDK。excluded 實際上是該意圖的說明文件，也是程式碼審查人員可用來仔細考量該值變更的鉤子。

回溯相容性

一般來說，SDK 類別會變更，讓 SDK Atom 接觸越來越多的目標對象。縮小 SDK Atom 的使用者集合，實際上會從其檢視畫面中刪除這些 API，如果未正確協調，可能會導致這些使用者中斷。

安全性考量

SDK 類別並非安全機制，惡意人士可以讀取 Fuchsia 開放原始碼專案中的所有 FIDL 定義，並以任何攻擊者能想到的惡意方式加以利用。這項機制僅限於讓工程師程序順利進行。

隱私權注意事項

所有 SDK 類別和適用的 SDK Atom 皆為公開資訊。

測試

SDK 類別會在建構期間透過建構設定強制執行。不過，我們沒有太多此機制的測試。變更 SDK 相關 GN 範本可能會導致機制中斷，進而讓 SDK Atom 納入不適當的 SDK 目標。我們有幾個多餘的機制 (包括 SDK 資訊清單)，用於找出設定錯誤，但我們依賴程式碼審查員，請他們注意 SDK 資訊清單和 SDK 類別之間的差異，以便找出 SDK 類別機制中的回歸現象。

說明文件

撰寫這份 RFC 的目的是記錄 SDK 類別的現況。針對開發人員的其他說明文件，則會說明 Fuchsia 發布的各種 SDK 提供哪些穩定性保證。

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

這種做法的主要缺點，是 SDK 類別可套用的粗略精細程度。舉例來說，您可以採用另一種方法，為個別 FIDL 通訊協定元素指派 SDK 類別，類似於為個別通訊協定元素指派 @available 屬性。

現有 SDK 類別機制的優點是，它可一律套用於所有類型的 SDK Atom。不過，我們可能會為特定類型的 SDK Atom (例如FIDL 通訊協定) 的變化趨勢。

既有技術與參考資料

大多數平台都設有類似機制，可在 API 穩定性提升時，逐步擴大 API 的目標對象。舉例來說，Apple 在開發 macOS 和 iOS 的 API 時，會使用類似的機制。在這些作業系統的開發過程中，每個架構都有三組 API：在架構本身可用的內部 API、可供作業系統版本中其他架構使用的私人 API，以及可供作業系統一般公開建構應用程式使用的公用 API。

其他平台的 SDK 發布程序中，有一個「標頭去除」步驟，會在將 SDK 發布給更廣大的目標對象前，移除標頭中的文字。使用「未去除」標頭的使用者可以依賴較大的 API 集，而使用去除標頭的使用者則可以依賴較小的 API 集。這個機制與 SDK 類別相似，但運作精細度較高，且通常有較少的目標對象等級。

  1. 目前合作夥伴的組合並未公開。隨著專案規模擴大，我們可能需要重新檢視合作夥伴關係的做法。 ↩