向后兼容性

概述

在对 DevTools 进行更改时，我们应该牢记某些向后兼容性要求。

总的来说，我们应该努力在继续对代码库进行更改时保持对现有服务器的功能支持。然而，有时这很难实现。

具体指南

重要的兼容性场景是

• Nightly 桌面客户端**必须**保持与发布通道服务器的现有兼容性。

这主要是为了简化跨平台用例，例如桌面 Nightly 与发布版 Fennec 的配合使用。

• 服务器**可以**使用特性来声明某个功能尚不支持。

这有助于我们支持替代环境，这些环境并非实现了所有可能的服务器功能。

当然，当新功能需要新的 Actor 方法才能发挥作用时，它将无法与不支持它的服务器一起使用。但是，我们仍然应该确保客户端在使用无关的现有功能时不会崩溃，至少在上述时间窗口过去之前是这样。

测试

目前比较困难的部分是，没有自动化测试来确保已满足上述指南。虽然我们希望在某个时候能够做到这一点，但目前需要进行手动测试。

测试此功能最简单的方法是针对发布通道上的 Android 版 Firefox 设备检查您的工作，以确保您正在更改的区域中的现有功能继续发挥作用。这并不能涵盖所有情况，但这是一个很好的开始。

或者，您可以连接到 Firefox 发布服务器。这可以通过多个步骤完成

1. 从命令行启动 Firefox 发布版，指定--start-debugger-server 和可用的端口（例如/Applications/Firefox.app/Contents/MacOS/firefox --start-debugger-server 6081）

2. 导航到一个页面，您可以在该页面上检查受补丁影响的 DevTools 部分是否仍然有效。

3. 构建并本地运行带有您要检查的补丁的 Firefox

4. 在此构建中，打开一个about:debugging 选项卡

5. 在Network Location 部分，使用 localhost 和您启动 Firefox 发布版实例时使用的调试器服务器端口填充主机（例如localhost:6081），然后按 Enter（或Add 按钮）

6. 侧边栏中将出现一个新项目，单击其Connect 按钮。

7. 接受出现的Incoming connection 弹出窗口

8. 再次单击侧边栏中的项目。您现在将看到 Firefox 发布版实例中正在运行的选项卡和工作程序列表。单击它们旁边的Inspect 按钮以打开连接到旧服务器的工具箱。

特性检测

从 Firefox 36 开始（感谢错误 1069673），您可以使用 Actor 特性检测来确定哪些 Actor 存在。

Target hasActor 助手

检测服务器是否具有 Actor：您只需要访问Toolbox 实例，所有面板在实例化时都会这样做。然后您可以执行以下操作

let hasSomeActor = toolbox.target.hasActor("actorTypeName");

hasActor 方法同步返回布尔值。

特性

在 Actor 上公开特性以将某些功能标记为可用或不可用。例如，如果向 Actor 添加了新的方法“someMethod”，则在 Actor 的 traits 对象中公开“supportsSomeMethod”标志，并将其设置为 true。在调试旧服务器时，该标志将丢失并默认为 false。

需要将特性转发到客户端，并由相应的 Front 存储或使用。公开特性的方法不是唯一的，但代码库中仍然存在一些常见的模式。

对于使用“form()”方法的 Actor，其 Front 由 protocol.js 自动创建，通常的模式是向 form 添加一个“traits”属性，其中包含 Actor 的所有特性。然后，Front 可以在其相应的“form()”方法中读取这些特性。示例

• NodeActor form 方法

• NodeFront form 方法

对于其他 Actor，有两种选择。第一种选择是在 Root Actor 上定义特性。这些特性可以通过 TargetMixin::getTrait() 和 DevToolsClient.traits 获取。第二种选择是在 Actor 上实现“getTraits()”方法，该方法将返回 Actor 的特性。示例

• CompatibilityActor getTraits 方法

• CompatibilitySpec getTraits 定义

• CompatibilityFront getTraits 方法

具有讽刺意味的是，“getTraits”需要进行向后兼容性处理。但是，除了在方法周围执行 try catch 之外，没有其他方法可以检查服务器上是否提供了“getTraits”。请参阅 CompatibilityFront 示例。

每当添加特性时，请务必添加相关的向后兼容性注释，以便我们知道何时可以删除该特性。

维护向后兼容代码

在引入向后兼容代码时，应添加注释以提供其他信息。为了简化将来的代码清理工作，注释应遵循以下语法：// @backward-compat { version XX } Detailed comment，其中XX 是添加此代码的 Firefox 版本。

下面是一个虚构的示例，说明它应该是什么样子

// @backward-compat { version 85 } For older server which don't have the AwesomeActor,
//                                 we have to do this another way.
if (!toolbox.target.hasActor("awesome")) {

当添加向后兼容代码的版本到达发布通道时，可以安全地删除该代码。因此，如果某些内容在 Firefox Nightly 85 中出现，则可以在 Firefox 85 发布时将其删除，即当 Firefox Nightly 为 87 时。搜索相应的@backward-compat 条目以检索可以删除的所有代码。