摘要

在 RFC-0050 之后，FIDL 方法请求或响应的参数以 (name1 Type1, name2 Type2) 的形式内联指定，这隐式定义了结构体的请求/响应类型，并将参数作为其成员。此 RFC 建议更改语法以显式指定顶级类型，例如 (struct { name1 Type1; name2 Type2; })。除了结构体之外，用户还可以指定联合或表的请求/响应类型。此 RFC 不会影响线格式。

另见：

• RFC-0050：FIDL 语法改版
• RFC-0086：RFC-0050 的更新：FIDL 属性语法
• RFC-0088：RFC-0050 的更新：FIDL 位、枚举和限制语法

术语

在此 RFC 中，“将类型封装在结构体中”是指获取现有类型并定义一个新结构体的过程，该结构体包含该类型的单个成员。例如，将类型 T 封装在结构体中是指定义新类型 type Wrapped = struct { my_t T; }。此技术可用于解决 FIDL 语言的某些限制。例如，uint8 不可为 null，但结构体可以为 null，因此可以先将 uint8 封装到结构体中，从而有效地使 uint8 可为 null。另请注意，T 和 Wrapped 具有完全相同的线格式。

设计初衷

更改语法以显式指定顶级类型（例如 (struct { name1 Type1; name2 Type2; })）具有两个主要优势：

• 将 ABI 影响放在语法的最前面，遵循 FIDL's 设计原则。例如，编写 (struct { name1 Type1; }) 而不是 (name1 Type1) 可以明确顶级请求或响应类型是结构体，因此添加或移除新形参与 ABI 或 API 不兼容。
• 使用户可以指定不同的顶级类型，而无需额外的间接级别，即将类型封装在结构体中。 除了通过内联定义提高可读性之外，这还允许 FIDL 编译器选择适当的名称，而不是将此负担交给开发者。一个示例场景是，方法的请求形参的可扩展性是优先事项 - 在这种情况下，用户可以使用表而不是结构体。

此 RFC 的引入时间与 RFC-0050 有两种关联方式：

• RFC 中引入的匿名布局使得可以重复使用此语法来指定请求/响应类型，而无需为其指定单独的名称。
• 此 RFC 中提出的语法更改可以分组到 RFC-0050 所需的现有 实现和迁移中，从而无需单独迁移。

设计

语法

之前：

protocol Oven {
  StartBake(temp Temperature);
  // message with no payload
  -> OnReady();
};

之后：

protocol Oven {
  StartBake(struct { temp Temperature; });
  // message with no payload
  -> OnReady();
};

所有可能的方法变体如下：

MyMethod(struct { ... }) -> (struct { ... });   // Two-way
MyMethod(struct { ... }) -> ();                 // Two-way, but response is empty
MyMethod() -> (struct { ... });                 // Two-way, but request is empty
MyMethod() -> ();                               // Two-way, but both request and response are empty
MyMethod() -> (struct { ... }) error zx.status; // Two-way; response leverages error syntax
MyMethod() -> () error zx.status;               // Error: must specify a type for success case.
MyMethod(struct { ... });                       // One-way
MyMethod();                                     // One-way, but request is empty
-> MyMethod(struct { ... })                     // Event
-> MyMethod();                                  // Event, but response is empty

更正式地说，

protocol-method = ( attribute-list ) , IDENTIFIER , parameter-list,
                  ( "->" , parameter-list , ( "error" type-constructor ) ) ;
protocol-event = ( attribute-list ) , "->" , IDENTIFIER , parameter-list ;
parameter-list = "(" , ( parameter ( "," , parameter )+ ) , ")" ;
parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;

的语法变为：

protocol-method = ( attribute-list ) , IDENTIFIER , method-params
                  ( "->" , method-params ( "error" type-constructor ) ) ;
protocol-event = ( attribute-list ) , "->" , IDENTIFIER , method-params;
method-params = "(" , type-constructor , ")"

type 的定义与 RFC-0050 中的定义相同，即它是对现有类型（如 MyType<args>:constraints）的 引用，或者是匿名 布局（例如 struct { name Type; }:constraints）。

虽然语法允许将任意类型用作请求和响应，但 FIDL 编译器将验证顶级类型是结构体、联合还是表。

如 RFC-0050 中RFC-0050，编译器会为任何内联的顶级请求或响应类型保留名称，这样就可以在需要时（例如，当形参数量增加时，为了提高可读性）从内联样式切换出来。例如，可以从以下内容更改为：

protocol MyProtocol {
    Foo(struct {
      // input param
      input uint32;
    }) -> (struct {
      // output param
      output uint32;
    });
};

更改为：

type FooRequest = struct {
  // input param
  input uint32;
};

type FooResponse = struct {
  // output param
  output uint32;
};

protocol MyProtocol {
    Foo(FooRequest) -> (FooResponse);
}

不会影响 API 或 ABI（假设 FooRequest 和 FooResponse 是编译器保留的名称）。

绑定

绑定的主要影响是，在某些情况下，与一组请求/响应形参对应的 API 是扁平的还是非扁平的，取决于请求或响应的顶级类型。目前，存在扁平化和非扁平化的生成 API 的实例。

在这里，“扁平化”API 是指绑定中直接使用请求和响应形参的任何 API，抽象出它们封装在结构体中的事实。例如，与 FIDL 方法 GetName(struct { id uint32; }) -> (struct { name string; }) 对应的客户端调用的函数签名在 HLCPP 中为：void GetName(uint32_t id, GetNameCallback callback)。FIDL 中指定的形参直接对应于 C++ 中的函数形参。

“非扁平化”API 是指顶级类型本身向用户公开的情况。在前面的示例中，这类似于：void GetName(GetNameRequest req, GetNameCallback callback)。GetNameRequest 对应于顶级结构体类型，并且将具有单个 uint32 id 字段。

在当前语法中，所有顶级请求或响应类型都是隐式结构体，因此扁平化参数以使其直接对应于函数签名的参数是可行的，因为添加或移除结构体成员无论如何都与 ABI 和 API 不兼容（即，生成的绑定中的此内联 API 不会对 FIDL 提供的保证添加额外的限制）。但是，对于支持添加和移除成员的表和并集，情况并非如此。因此，在某些情况下，如果用于表示方法（在此示例中为 C++ 中的位置函数实参）的语言构造的兼容性保证比顶级类型（例如表或联合）提供的兼容性保证更严格，则可能无法进行扁平化。再次使用上面的示例，这 意味着GetName(table { 1: id uint32; }) -> (table { 1: name string;}) 需要生成 void GetName(GetNameRequest req, GetNameCallback callback) 形式的非展平签名，以保持表顶级类型提供的 兼容性保证。

对于生成的函数或方法，某些编程语言（如 Dart）可以 通过在发送 端使用 命名实参 来解决此问题，但这在接收端仍然与源代码不兼容，因为 必须相应地向接收方法添加新形参。

总而言之，如果顶级类型是表或联合，则使用结构体的扁平化 API 的绑定代码可能需要提供不同的非扁平化 API。在绑定当前已生成非扁平化 API 的情况下（例如，LLCPP 中的 MyProtocol::MyRequest 或 MyProtocol::MyResponse），顶级结构体请求/响应或顶级联合或表请求/响应的 API 之间将没有这种区别。

JSON IR

maybe_request 和 maybe_response 的 JSON 条目将发生更改。旧架构：

"maybe_request": {
    "description": "Optional list of interface method request parameters",
    "type": "array",
    "items": {
        "$ref": "#/definitions/interface-method-parameter"
    }
},

变为：

"maybe_request_payload": {
    "description": "Optional type of the request",
    "$ref": "#/definitions/compound-identifier"
},

（maybe_response 的更改相同）

已存在与此形状匹配的 "maybe_request_payload" 字段，但 尚未在 JSON IR 中指定为 “更改消息的 表示形式” 工作的一部分。实际上，此 RFC 的 JSON IR 更改 将涉及完成从 "maybe_request" 到 "maybe_request_payload" 的迁移（请参阅实现）。

实现

此 RFC 的实现分为两个部分：第一部分是纯粹的表面更改，即修改所有现有文件以符合此处提出的新语法；第二部分是更改 FIDL 编译器和绑定，以允许将表和联合作为顶级类型。语法更改将作为更广泛的 RFC-0050 FIDL 语法转换的一部分来实现，但对联合和表顶级类型的支持可以推迟，以避免成为 FIDL 语法改进项目的阻碍。以 “新”语法编写的所有 FIDL 文件都应符合此 RFC 中列出的更改， 并且正式的 FIDL 语法将同时更新以反映其设计， 与 RFC-0050 的其余部分一样。

在现有绑定中，有些情况下，为请求和响应启用表和联合的顶级类型除了处理新的 JSON IR 格式外，不需要进行重大更改。如果不是这种情况，即绑定中的编码和解码代码依赖于顶级类型是结构体的假设，则有两种可能的方法：

• 第一种方法是在编码和解码之前先将所有表和联合封装到结构体中。这可能不受欢迎，因为它需要生成额外的类型，并为编码和解码添加额外的步骤。
• 另一种方法是修改编码/解码代码以支持非结构体的输入。目前，至少有一些代码 假定输入始终是结构体（例如，LLCPP 中的正确 特征仅为结构体生成，而 Rust 中的请求和响应 编码通过元组而不是结构体进行），但目前尚不清楚此假设的 数量 - 这需要 确定，以便了解权衡取舍，并最终在两种 方法之间做出决定。后一种方法可能具有方法调用之外的优势，例如，在持久性数据用例中，它无需将类型封装在结构体中。

JSON IR

作为 https://fxbug.dev/42157011 的一部分，迁移工作已在进行中，目的是将 "maybe_request" 和 "maybe_response" 字段移出 JSON IR，以便对 请求和响应类型的任何特殊处理仅发生在 FIDL 后端中。此工作在完成之前已暂停，但将恢复以实现此 RFC。 目前，C++ 后端是唯一仍在使用 "maybe_request" 和 "maybe_response" 的 fidlgen 后端（尽管使用 JSON IR 的其他库（例如 FIDL 编解码器）也需要更新）。

安全和隐私权

此 RFC 不会修改 FIDL 线格式，因此不会影响安全和隐私权。

测试

此 RFC 将使用现有基础架构进行测试：单元测试、黄金测试和集成测试（例如 FIDL 兼容性测试）。

文档

启用此功能后，应添加文档（包括示例）来描述新功能。

缺点、替代方案和未知因素

语法

此 RFC 中建议的语法使使用结构体作为顶级类型的常见路径更加冗长，因为它需要显式指定。 替代方案可能包括为常见情况引入语法糖（例如，保留结构体的当前语法，并为表和联合使用新的显式语法），但无论如何，显式语法的可读性被认为比减少冗长性更重要。

可能被认为不受欢迎的语法的另一部分是括号中的冗余：(struct { ... })，这也是 FTP-058 中讨论的问题。这里优先考虑一致性：保留大括号可确保请求中类型的语法与 FIDL 文件中任何其他位置的类型的语法相同。FTP-058 中采用的方法（通过将冗余大括号替换为空格来避免 冗余大括号，例如 MyMethod struct { ... } -> union { ... };）在这里也可能有效。在 FIDL 文本中，这种更实用的样式与提案的其余部分一致，并与 Fuchsia shell 中使用的语法一致，而在这里，它与 FIDL 的其余部分（更多基于 C 系列/Go 的语法）不一致。

最后，另一个建议的替代方案是更改用于指定类型的语法，以与方法形参语法保持一致：结构体将使用类似元组/记录的语法指定：type MyStruct = (foo Foo, bar Bar);。这样，当顶级类型是结构体时，我们就可以通过省略额外的括号集 MyMethod(foo Foo, bar Bar); 来保持相同的参数语法。作为完整示例，此建议如下所示：

// Declare a struct with two fields foo, bar.
type SomeStruct = (foo Foo, bar Bar);

protocol MyProtocol {
  // Declare a method with two request parameters.
  // The two parameters are stored in a struct.
  MyStructMethod(foo Foo, bar Bar);

  // Declare a method with two optional parameters.
  // The two parameters are stored in a table.
  MyTableMethod table { 1: foo Foo, 2: bar Bar };
};

绑定

如设计中所述，在许多情况下，绑定无法像对结构体那样对表和联合的生成 API 中的顶级类型成员进行展平或内联，以免引入额外的兼容性限制。关于何时内联方法的顶级类型成员的规则可能不容易让用户记住 - 这意味着他们需要依赖文档或生成的代码检查来确定每个 FIDL 协议方法的结果 API 是什么。与当前情况相比，这引入了一些复杂性，在当前情况下，绑定 API 会始终内联/扁平化顶级类型成员。

从理论上讲，可以通过从不扁平化请求或响应形参来提供一致的 API，但在实践中，这被认为是不可行的，因为它需要迁移依赖于此 API 的所有用户代码实例（即与 FIDL 方法交互的大部分用户代码）。

现有技术和参考资料

此 RFC 中建议的语法更接近 gRPC 中使用的语法，在 gRPC 中，方法请求和响应使用单个 protobuf 消息指定。

ctiller@google.com 之前曾提出过与此 RFC 类似的想法，允许使用序数语法（例如 MyMethod(1: foo Foo; 2: bar Bar)）来暗示顶级类型是表而不是结构体。主要区别在于，除了表和结构体之外，此 RFC 还支持顶级联合，这使得最初建议的语义变得模糊，因为联合也使用序数。