本頁面由 Cloud Translation API 翻譯而成。

RFC-0076：FIDL API 摘要

RFC-0076：FIDL API 摘要
狀態	已接受
領域	FIDL
說明	此為人類可讀 FIDL API 介面的格式。
問題	68955 年
毛皮變化	480497
作者	fmil@google.com
審查人員	pascallouis@google.com mkember@google.com jeremymanson@google.com gridman@google.com
提交日期 (年-月-日)	2021-03-16
審查日期 (年-月-日)	2021-03-16

編輯此 RFC

編輯 RFC 中繼資料

摘要

概述 FIDL API 介面的摘要，第一次輸出內容時，建議採用人類可讀的格式摘要說明 Fuchsia 來源中 FIDL 程式庫的 API 變更樹。

修訂條款 (2022 年 8 月)。此 RFC 描述了人類可讀的文字格式，以及。在導入過程中，JSON 格式，即新增相同的資訊 (https://fxrev.dev/480357)。取消喜歡 JSON 格式則可剖析回 Go 資料結構特別適合用於 fidl_api_diff。只有 JSON 格式我們現在使用的是今天，我們已移除文字格式以簡化維護工作。

提振精神

在撰寫本文時， Fuchsia 已開始多次努力。，目標是追蹤平台 API 介面異動情形。完成後，我們可以依據集體結果使用版本管理功能將平台開發與 SDK 使用的程式庫版本分離。

具體來說，在 FIDL 的網域中，您需要的是人類可讀的格式。 FIDL 程式庫的 API 介面表示法。這種表示法從這裡稱為「摘要」你可以透過多種方式

做為 FIDL 程式庫提供的 API 清查。

其他軟體生產 API 介面會保存類似的商品目錄例如 go。以將版本歸因於特定 API 。
做為偵測 FIDL API 中回溯不相容變更的基礎。

API 摘要功能可用來計算兩個 API 之間的差異並自動檢查單一 API 介面而變為另一個這是與目前的是程式庫的穩定 (稱為「正規化」) 形式來源是以可預測的方式串連所有來源的資料並移除註解和不相關的間距
做為 Compatibility Testing Suite 等其他作業的基石 (CTS，請參閱 RFC-0015) 用來偵測要在發生 API 變更時的情況

CTS 尤其需要削弱執行測試中的電池效能平台變動。掌握 API 介面的變更有助於只執行受變更影響的測試，儲存執行時間和運算資源

入門範例

請採用以下 FIDL 程式庫定義，來源為 fuchsia.accessibility.gesture。意見已經過簡化但程式庫為其他資料

library fuchsia.accessibility.gesture;

/// Maximum size of a returned utterance.
const uint64 MAX_UTTERANCE_SIZE = 16384;

/// Gesture types that accessibility offers to a UI component for listening.
enum Type {
    THREE_FINGER_SWIPE_UP = 1;
    THREE_FINGER_SWIPE_DOWN = 2;
    THREE_FINGER_SWIPE_RIGHT = 3;
    THREE_FINGER_SWIPE_LEFT = 4;
};

/// An interface to listen for accessibility gestures.
protocol Listener {
    /// When accessibility services detect a gesture, the listener is informed
    /// of which gesture was performed.
    OnGesture(Type gesture_type) -> (bool handled, string:MAX_UTTERANCE_SIZE? utterance);
};

/// An interface for registering a listener of accessibility gestures.
[Discoverable]
protocol ListenerRegistry {
    /// A UI registers itself to start listening for accessibility gestures
    /// through `listener`.
    Register(Listener listener) -> ();
};

上述程式庫的 API 摘要如下所示：

protocol/member fuchsia.accessibility.gesture/Listener.OnGesture(fuchsia.accessibility.gesture/Type gesture_type) -> (bool handled,string:16384? utterance)
protocol fuchsia.accessibility.gesture/Listener
protocol/member fuchsia.accessibility.gesture/ListenerRegistry.Register(fuchsia.accessibility.gesture/Listener listener) -> ()
protocol fuchsia.accessibility.gesture/ListenerRegistry
const fuchsia.accessibility.gesture/MAX_UTTERANCE_SIZE uint64 16384
enum/member fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_DOWN 2
enum/member fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_LEFT 4
enum/member fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_RIGHT 3
enum/member fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_UP 1
strict enum fuchsia.accessibility.gesture/Type uint32
library fuchsia.accessibility.gesture

請注意以下事項：

每個 API 元素都是單行文字。
每個 API 元素都是由其完整名稱參照。
API 元素在摘要中的顯示順序為固定。如果如果 FIDL 檔案中的宣告順序有所變更，這將不會影響 API 摘要的形狀。
只要使用 grep 等文字工具，就能輕鬆擷取摘要的各個部分。適用對象舉例來說，假設 API 摘要位於名為 fidl.api_summary 的檔案中，以下指令行只會擷取通訊協定的 API 介面：
```
cat fidl.api_summary | grep "fuchsia.accessibility.gesture/ListenerRegistry"
```
只擷取方法也相當簡單：
```
cat fidl.api_summary \
  | grep "fuchsia.accessibility.gesture/ListenerRegistry" \
  | grep "protocol/member"
```
基本 API 介面差異可透過以下方式產生：
```
diff -u fidl.old.api_summary fidl.new.api_summary
```
(假設 fidl.{old,new}.api_summary 包含原始和修改後的原始) API 介面)

需求條件

API 摘要「必須」清晰可讀，且可供處理提供簡易工具，例如 grep 和 diff。
產生的 API 摘要「必須」列出所有 FIDL 的元素以及對 API 介面影響的程式庫

設計

API 摘要格式包含具有 API 的程式庫相關資訊這種做法相關資訊請參閱「定義：來源」一節以及 RFC-0024 的相容性和可轉移性，以及 FIDL 繫結規格。這些只是資訊的一小部分存在於 FIDL IR 中，但會以更容易閱讀及傳簡訊公用程式請參閱摘要完整規則清單

所有 FIDL 語言結構都適用摘要規則。

每個 FIDL 宣告都使用完整名稱命名。因此，對於範例：

library fuchsia.accessibility.gesture;
enum Type { THREE_FINGER_SWIPE_UP = 1; };
protocol Listener {
  OnGesture(Type gesture_type);
};

ID OnGesture 一律會稱為 fuchsia.accessibility.gesture/Listener.OnGesture。

為方便閱讀及處理，檔案格式會刻意扁平。這表示 FIDL 成員 (出現在 struct 或 protocol) 以分行文字列出。這讓我們可以開始視需要擴充格式舉例來說可以納入日後的版本管理屬性。

單一 API 摘要檔案會列出整個 FIDL 中顯示的所有宣告程式庫中的各個檔案。

宣告在 API 摘要中的顯示順序為宣告順序獨立且穩定版相關聲明確實保持關閉，以利後續處理，但這並非正確性要求：任何與宣告順序無關且穩定的排序應該就足夠了

API 摘要排序

宣告的順序衍生自 FIDL AST：宣告與 AST 的後序週遊保持一致含有英數字元較小的完整名稱可用來選取層級的應用程式

我們將這個順序稱為「API 摘要」排序。

這個方法建議依照下列順序在 API 中宣告宣告摘要檔案：

fuchsia.accessibility.gesture/Listener.OnGesture
fuchsia.accessibility.gesture/Listener
fuchsia.accessibility.gesture/ListenerRegistry.Register
fuchsia.accessibility.gesture/ListenerRegistry
fuchsia.accessibility.gesture/MAX_UTTERANCE_SIZE
fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_DOWN
fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_LEFT
fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_RIGHT
fuchsia.accessibility.gesture/Type.THREE_FINGER_SWIPE_UP
fuchsia.accessibility.gesture/Type
fuchsia.accessibility.gesture

用於上述範例 FIDL 程式庫

API 摘要中的宣告順序與無論宣告在 .fidl 檔案中實際排序的方式為何，包括這些檔案可分割成多個檔案

API 摘要宣告結構定義

以下指定 API 摘要檔案的簡化 BNF，參照。

summary          ::= declaration_list

declaration_list ::= declaration
                   | declaration "\n" declaration_list
declaration      ::= library
                   | const
                   | bits
                   | bits_member
                   | enum
                   | enum_member
                   | struct
                   | struct_member
                   | union
                   | union_member
                   | protocol
                   | protocol_member
                   | alias

alias           ::= "alias" fqn
bits            ::= strictness "bits" fqn fp
bits_member     ::= "bits/member" fqn
const           ::= "const" fqn d fv
enum            ::= strictness "enum" ft
enum_member     ::= "enum/member" fqn fv
library         ::= "library" fqn
protocol        ::= "protocol" fqn
protocol_member ::= "protocol/member" fqn d
struct          ::= resourceness "struct" fqn
struct_member   ::= "struct/member" fqn ft [ fv ]
union           ::= strictness "union" fqn
union_member    ::= "union/member" fqn

resourceness    ::= "" | "resource"
strictness      ::= "flexible" | "strict"

d   ::= <FIDL protocol member type signature>
fp  ::= <FIDL primitive type>
fqn ::= <FIDL identifier>
ft  ::= <FIDL type>
fv  ::= <FIDL value>

實作

API 摘要是由程式實作 fidl_api_summarize。程式會將輸入 FIDL IR 和輸出 FIDL API 摘要，且兩個檔案名稱都指定為標記。叫用者應使用擴充功能 .api_summary 取得這個程式的輸出內容但這並非硬性規定。

成效

fidl_api_summarize 是 FIDL IR 檔案的簡易轉換方式。 Spot 檢查顯示，當程式執行時，該程式會在大約 0.1 秒內完成執行合理且龐大的程式庫這表示程式若能作為一般建構程序的一部分，於每個 FIDL 程式庫執行。

安全性考量

目前的 fidl_api_summarize 實作不會嘗試驗證並假設其輸入內容一律做為有效的輸出內容 (共 fidlc 個)。這可能會導致程式因格式錯誤而感到困惑儘管很難判斷是否可做為攻擊向量到 Fuchsia 建構流程。

隱私權注意事項

到目前為止，fidl_api_summarize 處理的資訊屬於以及程式碼存放區可以合理假設任何適用於輸入內容的隱私權規則也會一併套用至輸出內容

也就是說，如果用途是總結非公開 FIDL 程式庫程式碼輸出內容必須和程式庫程式碼一樣的隱私權標準

測試

我們使用大量範例輸入程式庫來測試這個程式，這些樣本對比本機輸出內容這樣就能確保 Fuchsia 程式碼集的生命週期內資料。

說明文件

fidl_api_summarize 的使用行為應隨以下項目的 FIDL 說明頁面： https://fuchsia.dev.

既有藝術品和參考資料

Go 語言 API 會定期產生 API 介面摘要。