RFC-0165：SDK 類別

RFC-0165：SDK 類別
狀態	已接受
區域	開發人員
說明	SDK 原子具有類別，可說明成熟度和目標對象。
Gerrit 變更	679446
作者	abarth@google.com
審查人員	dschuyler@google.com jamesr@google.com jeremymanson@google.com neelsa@google.com sebmarchand@google.com sethladd@google.com
提交日期 (年-月-日)	2022-05-13
審查日期 (年-月-日)	2022-05-31

摘要

每個 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 建立 JSON 中繼資料，所以將這些目標稱為 IDK 目標可能更準確。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 消費者使用¹。如果有人變更 fuchsia.bar，可能會導致依附於 fuchsia.bar 的合作夥伴中斷，進而對消費者造成影響，因此風險較高。

最後，請考慮使用 SDK 類別為 fuchsia.qux 的 FIDL 程式庫，這表示一般大眾可以使用 fuchsia.qux。public變更 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 的相容性窗口，這類 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 類別。這類現有模型的擴充功能不在本 RFC 的討論範圍內。

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

實作

SDK 類別已在 GN 規則中導入，用於建構 SDK。每個 SDK Atom 都有 category 參數，且值為下列其中一項：

• excluded：Atom 可能未納入 SDK；
• 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 類別的套用精細度較低。舉例來說，您可以想像另一種做法，就是將 SDK 類別指派給個別 FIDL 通訊協定元素，類似於將@available屬性指派給個別通訊協定元素的方式。

現有 SDK 類別機制的優點是，它適用於所有類型的 SDK Atom。不過，我們可能需要更精細的機制來處理特定類型的 SDK Atom (例如 FIDL 通訊協定) 的變化。

既有技術和參考資料

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

其他平台會在 SDK 發布程序中加入「標頭剝除」步驟，先移除標頭中的文字，再向更多使用者發布 SDK。使用「未移除」標頭的消費者可依賴的 API 數量，會比使用移除標頭的消費者多。這項機制與 SDK 類別類似，但精細度更高，且通常目標對象的漸層較少。