在 VS Code 中试用！

Visual Studio Code 中的严格空值检查

2019 年 5 月 23 日，作者：Matt Bierner，@mattbierner

安全带来速度

快速行动很有趣。发布新功能、让用户满意以及改进我们的代码库都很有趣。但是，与此同时，发布一个有 bug 的产品却不那么有趣。没有人喜欢遇到问题或在凌晨三点被叫醒处理事故。

尽管快速行动和发布稳定代码经常被认为是相互矛盾的，但事实并非如此。很多时候，导致代码脆弱和有 bug 的因素也正是拖慢开发速度的原因。毕竟，如果我们总是担心会破坏东西，又如何能快速行动呢？

在这篇文章中，我想分享 VS Code 团队最近完成的一项重大工程工作：在我们的代码库中启用 TypeScript 的严格空值检查。我们相信这项工作将使我们能够更快地行动并发布更稳定的产品。启用严格空值检查的动机是将 bug 理解为源代码中更大危害的症状，而不是孤立的事件。我将以严格空值检查为例，讨论我们工作的动机，我们是如何提出增量方法来解决问题，以及我们是如何实施修复的。这种识别和减少危害的通用方法可以应用于任何软件项目。

一个示例

为了说明在启用严格空值检查之前 VS Code 面临的问题，我们来考虑一个简单的 TypeScript 库。如果您是 TypeScript 新手，请不用担心；具体细节并不重要。这个虚构的例子仅仅是为了说明我们在 VS Code 代码库中遇到的问题类型，并提及一些针对此类问题的传统应对方式。

我们的示例库包含一个单独的 getStatus 函数，该函数从虚构网站的后端获取给定用户的状态

export interface User {
  readonly id: string;
}

/**
 * Get the status of a user
 */
export async function getStatus(user: User): Promise<string> {
  const id = user.id;
  const result = await fetch(`/api/v0/${id}/status`);
  const json = await result.json();
  return json.status;
}

看起来很合理。发布吧！

但在部署新代码后，我们发现崩溃数量激增。从调用堆栈来看，崩溃似乎发生在我们的 getStatus 函数中。糟糕！

再往前回溯一点，似乎我们的一位同事工程师错误地尝试通过调用 getStatus(undefined) 来获取当前用户的状态。当代码尝试访问 undefined.id 时，这会导致一个异常。简单的错误。既然我们知道了原因，就来修复它吧！

因此，我们更新了调用代码，更新 getStatus 以处理 undefined，并在我们的文档注释中添加了一个有用的警告

/**
 * Get the status of a user
 *
 * Don't call this with undefined or null!
 */
export async function getStatus(user: User): Promise<string> {
  if (!user) {
    return '';
  }
  const id = user.id;
  const result = await fetch(`/api/v0/${id}/status`);
  const json = await result.json();
  return json.status;
}

而且因为我们是真正的工程师，我们也编写了一个测试

it('should return empty status for undefined user', async () => {
  assert.equals(getStatus(undefined), '');
});

太棒了！不再崩溃了。而且我们甚至恢复了 100% 的测试覆盖率！我们的代码现在一定是完美的。

几天过去了，然后：砰！有人在我们的日志中发现了一些奇怪的东西，大量的请求指向 /api/v0/undefined/status。那可真是个奇怪的用户名...

于是我们再次调查，再次修复代码，添加更多测试。也许还会给那些调用 getStatus({ id: undefined }) 的人发一封消极攻击的电子邮件。

/**
 * Get the status of a user
 *
 * !!!
 * WARNING: Don't call this with undefined or null, or with a user without an id
 * !!!
 */
export async function getStatus(user: User): Promise<string> {
  if (!user) {
    return '';
  }
  const id = user.id;
  if (typeof id !== 'string') {
    return '';
  }
  const result = await fetch(`/api/v0/${id}/status`);
  const json = await result.json();
  return json.status;
}

完美。但是，为了确保万无一失，我们要求所有引入 getStatus 调用的更改都必须经过高级工程师的批准。这应该能永久性地杜绝这些恼人的 bug...

也许这次我们可以多撑几天，直到下一次崩溃。甚至几个月。但是，除非我们的代码再也不被更改，否则总会有一次。如果不是在这个特定函数中，那也会在我们的代码库的其他地方。

更糟的是，现在每一次更改都需要：防御性地检查 undefined、修改或添加新测试，以及获得团队批准。这是怎么回事？我们都在尽自己的职责，但仍然有 bug！一定有更好的方法。

识别危害

虽然上面例子中的 bug 可能看起来很明显，但我们在开发 VS Code 时也遇到了同样类型的问题。每一次迭代，我们都会修复与意外的 undefined 相关的 bug。我们会添加测试。我们会发誓成为更好的工程师。这些都是传统的应对方式，然而在下一次迭代中，同样的事情又会再次发生。这不仅导致一些用户在 VS Code 上获得糟糕的体验，这些 bug 以及我们对它们的应对也减慢了我们开发新功能或更改现有源代码的速度。

我们意识到需要以一种新的方式来理解我们的 bug，它们不再是孤立的事件，而是更大问题的症状/信号。我们对这些 bug 的反应以及因无法快速行动而产生的沮丧也是症状。当我们开始讨论这些症状的根本原因时，我们发现了一些常见的：

  • 未能捕获简单的编程错误，例如访问 null 或 undefined 上的属性。
  • 接口规范不足。哪些参数可以是 undefined 或 null，哪些函数可能返回 undefined 或 null？函数实现者通常与调用者在不同的假设下工作。
  • 类型怪异。undefined 与 null。undefined 与 false。undefined 与空字符串。
  • 感觉我们无法信任代码或安全地重构它。

识别根本原因是一个很好的第一步，但我们想深入探讨。在所有这些情况下，是什么危害让善意的工程师首先引入了 bug？我们很快识别出了所有这些问题共有的一个显著危害：VS Code 代码库中缺乏严格空值检查。

要理解严格空值检查，你必须记住 TypeScript 的目标是为 JavaScript 添加类型。TypeScript 的 JavaScript 传统导致的结果是，默认情况下，TypeScript 允许 undefined 和 null 用于任何值

// Without strict null checking, all of these calls are valid

getStatus(undefined); // Ok
getStatus(null); // Ok
getStatus({ id: undefined }); // Ok

虽然这种灵活性使得从 JavaScript 迁移到 TypeScript 变得更简单，但我们虚构网站的示例库表明它也是一种危害。这种危害也是我们在开发 VS Code 时发现的四个根本原因（以及许多其他原因）的核心。

不过，值得庆幸的是，TypeScript 提供了一个名为严格空值检查的选项，该选项会使 undefined 和 null 被视为不同的类型。使用严格空值检查时，任何可能为空的类型都必须进行相应的标注

// With "strictNullCheck": true, all of these produce compile errors

getStatus(undefined); // Error
getStatus(null); // Error
getStatus({ id: undefined }); // Error

修复孤立的代码行或添加测试是一种被动解决方案，只能修复那些特定的 bug。启用严格空值检查是一种主动解决方案，它不仅能修复我们每月看到的报告的 bug，还能阻止这类 bug 在未来发生。不再需要忘记检查可选属性是否有值。不再需要怀疑函数是否能返回 null。好处显而易见。

制定增量计划

问题在于，我们不能仅仅启用一个编译器标志，然后一切都会神奇地修复。核心 VS Code 代码库包含约 1800 个 TypeScript 文件，总计超过五十万行。使用 "strictNullChecks": true 编译它会产生约 4500 个错误。哎呀！

此外，VS Code 由一个小型核心团队组成，我们喜欢快速行动。分支代码来修复这 4500 个严格空值错误会增加巨大的工程开销。而且，你甚至从何开始？从头到尾检查错误列表吗？此外，在分支中的更改对主分支没有帮助，而团队的大多数成员仍然会在主分支上工作。

我们希望制定一个计划，能够立即开始，逐步将严格空值检查的好处带给团队中的所有工程师。这样，我们就可以将工作分解为可管理的更改，每次小的更改都能让代码更安全一点。

为此，我们创建了一个名为 tsconfig.strictNullChecks.json 的新 TypeScript 项目文件，该文件启用了严格空值检查，最初包含零个文件。然后我们选择性地将单个文件添加到这个项目中，修复这些文件中的严格空值错误，然后提交更改。只要我们添加的文件要么没有导入，要么只导入了其他已进行严格空值检查的文件，每次迭代我们只需修复少量错误。

{
  "extends": "./tsconfig.base.json", // Shared configuration with our main `tsconfig.json`
  "compilerOptions": {
    "noEmit": true, // Don't output any javascript
    "strictNullChecks": true
  },
  "files": [
    // Slowly growing list of strict null check files goes here
  ]
}

虽然这个计划看起来合理，但一个问题是，在主分支工作的工程师通常不会编译 VS Code 中已严格空值检查的部分。为了防止意外地回溯到已进行严格空值检查的文件，我们添加了一个持续集成步骤来编译 tsconfig.strictNullChecks.json。这确保了如果提交的内容导致严格空值检查退化，就会破坏构建。

我们还编写了两个简单脚本，以自动化一些与将文件添加到严格空值检查项目相关的重复任务。第一个脚本打印出符合严格空值检查条件的文件列表。如果一个文件只导入了本身已进行严格空值检查的文件，则认为它符合条件。第二个脚本尝试自动将符合条件的文件添加到严格空值项目中。如果添加文件没有导致编译错误，则将其提交到 tsconfig.strictNullChecks.json。

我们还考虑过自动化一些严格空值修复本身，但最终我们放弃了。严格空值错误通常是一个很好的信号，表明源代码应该被重构。也许一个类型为空没有很好的理由。也许调用者应该处理 null 而不是实现者。手动审查和修复这些错误让我们有机会使我们的代码更好，而不是强行使其与严格空值兼容。

执行计划

在接下来的几个月里，我们缓慢地增加了严格空值检查文件的数量。这通常是繁琐的工作。大多数严格空值错误都很简单：只需添加空值注解。对于其他错误，很难理解代码的意图。一个值是故意未初始化还是实际上存在编程错误？

一般来说，我们尽可能避免在主代码库中使用 TypeScript 的非空断言。我们在测试中更自由地使用它，理由是如果测试代码中缺乏空值检查会导致异常，那么测试无论如何都会失败。

整个过程中一个令人沮丧的方面是，VS Code 代码库中严格空值错误的总数似乎从未减少。甚至，如果你在启用严格空值检查的情况下编译整个 VS Code，我们所有的严格空值工作实际上似乎导致错误总数增加！这是因为严格空值修复通常会产生连锁效应。正确标注一个函数可以返回 undefined 可能会为该函数的所有使用者引入严格空值错误。我们没有担心剩余错误的总数，而是专注于已进行严格空值检查的文件数量，并努力确保这个总数永不回退。

还需要注意的是，启用严格空值检查并不能神奇地阻止与严格空值相关的异常发生。例如，any 类型或错误的类型转换可以轻易绕过严格空值检查

// strictNullCheck: true

function double(x: number): number {
  return x * 2;
}

double(undefined as any); // not an error

就像访问数组越界元素一样

// strictNullCheck: true

function double(x: number): number {
  return x * 2;
}

const arr = [1, 2, 3];

double(arr[5]); // not an error

此外，除非您同时启用 TypeScript 的严格属性初始化，否则如果您访问尚未初始化的成员，编译器将不会报错

// strictNullCheck: true

class Value {
  public x: number;

  public setValue(x: number) {
    this.x = x;
  }

  public double(): number {
    return this.x * 2; // not an error even though `x` will be `undefined` if `setValue` has not been called yet
  }
}

这项工作的目的绝不是要消除 VS Code 中 100% 的严格空值错误——那将极其困难，甚至不可能——而是要防止绝大多数常见的严格空值相关错误。这也是一个清理代码并使其更安全地重构的好机会。达到 95% 的目标对我们来说是可以接受的。

您可以在 GitHub 上找到我们完整的严格空值检查计划及其执行情况。VS Code 团队的所有成员以及许多外部贡献者都参与了这项工作。作为这项工作的推动者，我进行了最多的严格空值相关修复，但这只占用了我大约四分之一的工程时间。在此过程中肯定有一些痛苦，包括许多严格空值回退只有在提交后才被持续集成捕获的恼人之处。严格空值工作也引入了一些新 bug。然而，考虑到更改的代码量，一切都进行得异常顺利。

最终为整个 VS Code 代码库启用严格空值检查的更改相当平淡：它修复了更多代码错误，删除了 tsconfig.strictNullChecks.json，并在我们的主 tsconfig 中设置了 "strictNullChecks": true。这种缺乏戏剧性的结果正是计划中的。至此，VS Code 已经进行了严格空值检查！

总结

当向人们讲述这个项目时，我听到的一个常见问题是：它修复了多少 bug？我认为这个问题并没有真正的意义。对于 VS Code，我们从未遇到过无法修复与缺乏严格空值检查相关的 bug 的问题。通常，这涉及到添加一个条件判断，也许还有一两个测试。但我们却反复看到同类型 bug 的出现。修复这些 bug 不必要地拖慢了我们的速度，也意味着我们无法完全信任我们的代码。代码库中缺乏严格空值检查是一种危害，而 bug 只是这种危害的症状。通过启用严格空值检查，我们已经做了大量工作来防止一整类 bug 的发生，此外还为我们的代码库和工作方式带来了许多其他好处。

这篇文章的目的并不是要成为一个关于在大型代码库中启用严格空值检查的教程。如果这个问题确实适用于您，希望您看到这可以通过理智的方式实现，而无需任何魔法。（我补充一点，如果您正在启动一个新的 TypeScript 项目，请帮未来的自己一个忙，默认从 "strict": true 开始。）

我希望您能从中领悟到的是，很多时候，对 bug 的反应要么是添加测试，要么是归咎于他人。“鲍勃当然应该知道在访问那个属性之前检查 undefined。”人们的本意是好的，但他们会犯错。测试很有用，但也有成本，并且只测试我们编写它们来测试的内容。

相反，当你遇到一个 bug 或其他阻碍你前进的问题时，不要急于修复并转向下一个问题，而是停下来真正探究其原因。它的根本原因是什么？它揭示了哪些危害？例如，也许你的源代码包含一种危险的编码模式，需要进行一些重构。然后，以与其影响成比例的方式解决危害。你不需要重写所有内容。做最少量的前期工作，并在有意义时自动化。减少危害，今天就让世界逐步变得更好。

我们对 VS Code 的严格空值检查采用了这种方法，未来也会将其应用于其他问题。我希望无论您从事何种项目，都能发现它很有用。

编程愉快，

Matt Bierner，VS Code 团队成员 @mattbierner