Visual Studio Code 中的严格空值检查
2019 年 5 月 23 日，作者：Matt Bierner，@mattbierner
安全带来速度
快速行动很有趣。发布新功能、让用户满意、改进代码库都很有趣。但是，与此同时，发布有缺陷的产品并不有趣。没有人喜欢收到问题报告，或者在凌晨三点被叫醒处理突发事件。
虽然快速行动和发布稳定代码经常被认为是互不相容的，但事实并非如此。很多时候，导致代码脆弱和存在缺陷的因素，也正是减缓开发速度的原因。毕竟，如果我们总是担心会破坏东西，又怎能快速行动呢？
在这篇文章中，我想分享 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？通常，函数的实现者与调用者有着不同的假设。 - 类型怪异之处。
undefinedvsnull。undefinedvsfalse。undefinedvs 空字符串。 - 感觉我们无法信任代码或安全地重构它。
识别根本原因是一个很好的第一步，但我们想更深入。在所有这些情况下，是什么危害让一个善意的工程师首先引入了 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 文件，包含超过 50 万行代码。使用 "strictNullChecks": true 编译它会产生大约 4500 个错误。哎呀！
此外，VS Code 由一个小型核心团队组成，我们喜欢快速行动。分支出代码来修复这 4500 个严格空值错误会增加大量的工程开销。而且你该从何处开始呢？从上到下逐个解决错误列表？此外，分支中的更改对主分支没有帮助，因为团队中的大多数人仍将在主分支上工作。
我们希望制定一个能立即为团队所有工程师带来严格空值检查好处的增量计划。这样，我们就可以将工作分解成可管理的更改，每次小的更改都会使代码更安全一点。
为此，我们创建了一个新的 TypeScript 项目文件 tsconfig.strictNullChecks.json，它启用了严格空值检查，最初包含零个文件。然后我们有选择地将单个文件添加到这个项目中，修复这些文件中的严格空值错误，然后签入更改。只要我们添加的文件要么没有导入，要么只导入其他已经进行严格空值检查的文件，每次迭代我们只需要修复少量错误。
{
"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 的非空断言。我们在测试中更自由地使用它，理由是如果测试代码中缺乏 null 检查会导致异常，那么测试无论如何都会失败。
整个过程中令人沮丧的一个方面是，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