RFC-0231：FIDL 版本控制替换语法

摘要

更改 FIDL 的 @available 属性以支持 replaced 参数。时间是 与 removed 类似，但会验证替换项是否是同一版本的 added。

背景

RFC-0083：FIDL 版本控制引入了 @available 属性， FIDL API 版本控制。该设计的一个要求是，允许对 更改。也就是说，v1.fidl 在单个 versioned.fidl 中转换到任意不同的 v2.fidl 文件。该设计满足了这一要求，因为它允许多个元素 可以使用相同的名称，只要它们的版本范围不重叠即可

例如，可考虑将 @discoverable 属性添加到协议 P 的以下位置： 版本 5。我们无法直接用 @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

社交化：我与 FIDL 团队和平台讨论了这一想法 在编写 RFC 之前对版本控制工作组进行命名。

设计

• 引入一个名为 replaced 的新 @available 参数。它的行为方式与 removed，不过它的验证方式不同，如下所述。它可以 用于代替 removed。library

• 如果某个元素标记为 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 会验证 另一个Foo标记为了added=2。然而，它的效果不类似 验证子元素 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 版本控制：替换元素”的内部文档。

此方案非常特定于 FIDL 版本控制的设计，因此 据我所知。