我们使用 API 兼容性测试来确保 SDK 用户以受支持的平台为目标 对 FIDL API 的更改不会破坏 API 级别。发布于 合作伙伴 Fuchsia SDK 应自动进行反向 API 测试 兼容性。本文档介绍了什么是 API 兼容性测试以及如何使用 。
概念
FIDL 版本控制
读者应熟悉 FIDL 版本控制。
API 级别
为了理解 API 兼容性测试，请务必对 Fuchsia API 级别。API 级别表示在构建 应用。它们是分配给 Fuchsia 平台的无符号 64 位整数 以升序排列。
您需要注意以下两个 API 级别：
- 开发中的 API 级别 - Fuchsia 开发者在此级别进行补充更改。
- 稳定的 API 级别 - 该级别稳定，其显示区域不会改变。
平台版本控制的当前实现尚未反映这一点： 在 Fuchsia 源代码树中，我们记录了 API 和 ABI 的版本历史记录，以及级别 状态（“开发中”和“受支持”，也称为“稳定”） //sdk/version_history.json.
API 级别演变
API 级别会经历几个阶段，如下图所示：
+----------------+ freeze +--------+ drop +-------------+
START -> | in-development | -----> | stable | -----> | unsupported |
+----------------+ +--------+ +-------------+
开发中
在此阶段，由于新的 API 元素，API 级别正在积极发展中 可能会引入、弃用等等。 不允许对在此级别引入的 API 进行重大更改，并且贡献者 应确保没有合作伙伴仍在使用在此级别移除的 API。
稳定版
API 级别无法再接收更改。贡献者应开始介绍 面向合作伙伴推出的下一个 API 级别。当我们“冻结”时API 级别，该级别可能不会再收到更改。这通常会立即发生 。此产品将至少在 6 周内或直到 Fuchsia 平台 停止支持它可以在此级别弃用 API，但不能将其删除。
不支持
如果我们放弃对某个等级的支持，那么 Fuchsia 贡献者可以随意删除或 修改此级别的 API， 停止针对此级别运行兼容性测试。我们不再保证 最终用户可以 以此 API 级别为目标平台。
解决兼容性问题
通常，兼容性问题可以通过在 FIDL 中添加 @available 注解来解决
声明。
下面是更改 FIDL API 时应遵循的一些有效准则。
- 使用
@available(added=HEAD)为新的、尚不稳定的 API 添加注解。 - 为可随时提供给合作伙伴使用且不会发生变化的新稳定版 API 添加注解
尽在
@available(added=NEXT)。 - 移除 API 时，请先确保没有任何合作伙伴仍在使用该 API，然后
为旧 API 添加
@available(..., removed=NEXT)注解。
如需查看更多示例，请参阅 API 演变指南和 FIDL 兼容性指南。