🚀 在 VS Code 中！

严格的空值检查 Visual Studio Code

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

安全许可速度

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

尽管快速行动和发布稳定的代码通常被认为是互不相容的，但事实不应如此。很多时候，使代码脆弱和有缺陷的相同因素也会减慢开发速度。毕竟，如果我们总是担心破坏东西，我们怎么能快速行动呢？

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

一个例子

为了说明 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 的调用的更改都必须由高级工程师批准。这应该永久阻止这些讨厌的错误...

也许这次我们在下一次崩溃之前度过了更多天。甚至几个月。但是，除非我们的代码永远不再更改，否则肯定会发生一次。即使不是在这个特定函数中，也会在代码库中的其他地方发生。

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

识别危险

虽然上面的示例中的错误可能看起来很明显，但我们在开发 VS Code 时也遇到了相同类型的问题。每次迭代，我们都会修复与意外的 undefined 相关的错误。我们会添加测试。我们会发誓要做更好的工程师。这些都是传统的应对措施，但在下一次迭代中，这种情况会再次发生。这不仅导致一些用户对 VS Code 的体验不佳，这些错误以及我们对这些错误的反应也减慢了我们在开发新功能或更改现有源代码时的速度。

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

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

识别根本原因是一个良好的第一步，但我们想更深入地研究。在所有这些情况下，是什么危害使一个善意的工程师首先引入了错误？我们很快就识别出一个所有这些问题共有的明显危害：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

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

提出一个增量计划

问题是我们不能只启用编译器标志，一切都会神奇地修复。核心 VS Code 代码库包含大约 1800 个 TypeScript 文件，超过 50 万行代码。使用 "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 而不是实现者。手动审查和修复这些错误使我们有机会使我们的代码更好，而不是强行使其与严格的空值兼容。

执行计划

在接下来的几个月中，我们缓慢地扩展了严格空值检查文件的数量。这通常是乏味的工作。大多数严格的空值错误都很简单：只需添加 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 团队的所有成员以及许多外部贡献者都参与了这项工作。作为这项工作的驱动者，我进行了最多的严格空值相关修复，但这只占用了我大约四分之一的工程时间。在此过程中肯定有一些痛苦，包括一些恼人之处，即许多严格的空值回归仅在签入后才被持续集成捕获。严格的空值工作也引入了一些新错误。但是，考虑到更改的代码量，一切都进行得非常顺利。

最终为整个 VS Code 代码库启用严格的空值检查的更改相当平淡无奇：它修复了一些代码错误，删除了 tsconfig.strictNullChecks.json，并在我们的主 tsconfig 中设置了 "strictNullChecks": true。缺乏戏剧性完全符合计划。至此，VS Code 进行了严格的空值检查！

结论

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

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

我希望您记住的是，对于错误或减慢您速度的其他事情，通常的反应要么是添加测试，要么是责备。“当然，Bob 应该知道在访问该属性之前检查 undefined。”人们的本意是好的，但会犯错误。测试很有用，但也需要成本，并且只测试我们编写它们进行测试的内容。

相反，当您遇到错误或减慢您速度的其他事情时，不要急于修复并继续处理下一个问题，而是花点时间真正探索导致错误的原因。它的根本原因是什么？它揭示了哪些危害？例如，也许您的源代码包含危险的编码模式，并且可以使用一些重构。然后努力以与其影响成比例的方式解决危害。您不需要重写所有内容。做所需的最小量的前期工作，并在有意义时进行自动化。减少危害，让世界今天变得更好。

我们对严格的空值检查 VS Code 采用了这种方法，并将将其应用于未来的其他问题。我希望您也觉得它有用，无论您正在从事什么类型的项目。

祝您编码愉快，

Matt Bierner，VS Code 团队成员 @mattbierner