RFC-0165：SDK 类别

RFC-0165：SDK 类别
状态	已接受
领域	开发者
说明	SDK Atom 具有描述其成熟度和目标受众群体的类别。
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 是创建核心 SDK 的 build 目标的 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 使用方使用。当有人更改 fuchsia.bar 时，破坏使用方的风险更大，因为他们可能会破坏依赖于 fuchsia.bar 的合作伙伴。

最后，请考虑 SDK 类别为 public（这意味着 fuchsia.qux 可供公众使用）的 fuchsia.qux FIDL 库。更改 fuchsia.qux 的风险非常高，因为公众开发的软件集可能是无限且不可知的。

除了定义同中心增加的 API 使用方集之外，SDK 类别还定义了增加的稳定性期。例如，fuchsia.foo 每天之间可能会有很大变化，因为 internal 类别限制了对 Fuchsia 项目本身的曝光。更改 fuchsia.foo 的人可以同时更改所有客户端和服务器，这意味着 API 所需的稳定性窗口要么很小，要么为零。

相比之下，Fuchsia 与合作伙伴项目之间达成的协议中包含对兼容性窗口的预期。例如，我们目前与合作伙伴达成协议，将维护六周的兼容性窗口期，但在即将发布的 RFC 中可能会发生变化。这种协议意味着 fuchsia.bar 不能在第二天发生大幅变化。相反，我们需要逐步更改 fuchsia.bar，以便保持兼容期。

目前，Fucsia 没有任何 SDK 类别为 public 的 SDK Atom，这意味着 Fuchsia 未承诺使用其 API 为公众提供支持。不过，Fuchsia 项目将开始使用其 API 为公众提供支持。届时，Fucsia 项目将需要为这些 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 类别已在构建 SDK 的 GN 规则中实现。每个 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 是关于该 intent 的文档，也是代码审核人员要谨慎考虑对该值的更改的钩子。

向后兼容性

通常情况下，SDK 类别会因向越来越多的受众群体公开 SDK Atom 而发生变化。缩小 SDK Atom 的使用方集可有效地从其视图中删除这些 API，如果协调不当，则可能会破坏这些使用方。

安全注意事项

SDK 类别不是安全机制。恶意攻击者可以从 Fuchsia 开源项目读取所有 FIDL 定义，然后以攻击者能想象的任何恶意方式利用这些定义。此机制仅限于使工程流程更顺畅运行。

隐私注意事项

关于 SDK 类别及其适用的 SDK Atom 的所有信息都是公开的。

测试

SDK 类别在构建时通过 build 配置强制执行。不过，我们对此机制的测试并不多。对与 SDK 相关的 GN 模板的更改可能会破坏该机制，从而导致 SDK Atom 被纳入不当 SDK 目标中。我们有几种冗余机制（包括 SDK 清单）来发现错误配置，但我们依靠代码审核人员发现 SDK 清单和 SDK 类别之间的不一致，从而确定 SDK 类别机制中的回归问题。

文档

编写此 RFC 的目的是记录 SDK 类别的现状。我们还提供了其他面向开发者的文档，其中介绍了 Fuchsia 针对 Fuchsia 发布的各种 SDK 做出的稳定性承诺。

缺点、替代方案和未知情况

这种方法的主要缺点是，系统能够应用 SDK 类别时较为粗略。例如，您可以设想另一种方法，即为各个 FIDL 协议元素分配 SDK 类别，这类似于为各个协议元素分配 @available 属性的方式。

现有 SDK 类别机制的优势在于，它统一适用于所有类型的 SDK Atom。但是，对于某些类型的 SDK Atom（例如，FIDL 协议）。

早期技术和参考资料

大多数平台都有类似的机制，可以在 API 变得更稳定时逐步扩大 API 的受众群体。例如，Apple 在开发适用于 macOS 和 iOS 的 API 时会使用类似的机制。在这些操作系统的开发过程中，每个框架都有三组 API：在框架本身内可用的内部 API、可供操作系统 build 中包含的其他框架使用的私有 API，以及可供操作系统的通用公共构建应用使用的公共 API。

一些其他平台在其 SDK 发布流程中有一个“标头剥离”步骤，用于在将 SDK 发布给更广泛的受众群体之前从头文件中移除文本。使用“未剥离”头文件的使用方可能会依赖于更多 API，而这些使用方是使用剥离的头文件的。此机制与 SDK 类别类似，但运作的粒度更高，而且受众群体分级通常更少。