TypeScript 鉴别联合类型：优雅处理条件类型与可选属性

本文深入探讨了在 typescript 中处理基于条件的可选属性时常见的“可能为 undefined”错误。通过详细分析问题根源，即单个接口中可选属性与判别属性的关联性不足，文章提出了使用鉴别联合类型（discriminated union）作为解决方案。教程将展示如何重构类型定义以实现精确的类型收窄，从而消除编译错误，提升代码的类型安全性和可维护性。

理解 TypeScript 中可选属性的挑战

在 TypeScript 中，我们经常会遇到需要定义一个对象，其结构根据某个特定属性的值而变化的情况。例如，一个表示“形状”的接口，可能根据 kind 属性是 "circle" 还是 "square" 来拥有不同的属性（如 radius 或 sideLength）。一个直观但容易出错的定义方式如下：

interface Shape {
  kind: "circle" | "square";
  radius?: number; // 圆形特有，可选
  sideLength?: number; // 正方形特有，可选
}

function getArea(shape: Shape): number | undefined {
  if (shape.kind === "circle" && Object.hasOwn(shape, "radius")) {
    // 'shape.radius' is possibly 'undefined'. ts(18048)
    return Math.PI * shape.radius**2;
  }
  else if (shape.kind === "square" && "sideLength" in shape) {
    // 'shape.sideLength' is possibly 'undefined'. ts(18048)
    return shape.sideLength**2;
  }
  return undefined;
}

尽管我们在 if 条件中明确使用了 Object.hasOwn() 或 in 运算符来检查属性是否存在，TypeScript 编译器仍然会抛出 ts(18048) 错误，提示 shape.radius 或 shape.sideLength 可能为 undefined。

为什么会出现这个错误？

问题的核心在于，对于 TypeScript 而言，Object.hasOwn(shape, "radius") 或 "sideLength" in shape 仅仅确认了对象实例上存在名为 radius 或 sideLength 的属性。然而，这并不足以让 TypeScript 编译器理解在 shape.kind === "circle" 的上下文里，radius 属性的值就一定是一个 number 类型而非 undefined。在原始的 Shape 接口定义中，radius 和 sideLength 被标记为可选属性 (?)，这意味着它们在任何 Shape 类型的对象上都可能存在或不存在，并且即使存在，其值也可能被显式地设置为 undefined。TypeScript 的类型收窄机制在这种情况下无法充分关联 kind 属性和可选属性的存在性及其非 undefined 的值。

引入鉴别联合类型（Discriminated Union）

解决上述问题的最佳实践是使用 TypeScript 的鉴别联合类型（Discriminated Union）。这种模式允许我们定义一个联合类型，其中每个成员都是一个具有共同的“鉴别属性”（discriminant property）的对象字面量，且该鉴别属性的值是字面量类型。通过检查鉴别属性的值，TypeScript 能够精确地收窄到联合类型中的特定成员，从而确保其他相关属性的存在性和类型。

如何构建鉴别联合类型

我们将 Shape 接口重构为一个类型别名，它是一个由多个对象类型组成的联合：

type Shape =
  | {
      kind: 'circle'; // 鉴别属性，值为字面量 'circle'
      radius: number; // 当 kind 为 'circle' 时，radius 必须存在且为 number
    }
  | {
      kind: 'square'; // 鉴别属性，值为字面量 'square'
      sideLength: number; // 当 kind 为 'square' 时，sideLength 必须存在且为 number
    };

在这个新的 Shape 类型定义中：

可图大模型

可图大模型（Kolors）是快手大模型团队自研打造的文生图AI大模型

32

查看详情

• kind 属性是我们的鉴别属性。
• 每个联合成员都有一个字面量类型的 kind 值（'circle' 或 'square'）。
• 关键在于，在每个联合成员内部，其特有的属性（如 radius 或 sideLength）不再是可选的，而是必需的。这意味着，如果一个 Shape 对象的 kind 是 'circle'，那么它必然会有一个 number 类型的 radius 属性。

使用鉴别联合类型消除错误

有了鉴别联合类型，getArea 函数可以被安全地重写，并且 TypeScript 能够正确地进行类型收窄：

function getArea(shape: Shape): number { // 返回类型现在可以是 number，因为所有形状都有明确的面积计算
  if (shape.kind === "circle") {
    // 在此代码块中，TypeScript 知道 shape 的类型是 { kind: 'circle'; radius: number; }
    // 因此 shape.radius 必然是 number，不再有 'possibly undefined' 错误
    return Math.PI * shape.radius**2;
  }
  else if (shape.kind === "square") {
    // 在此代码块中，TypeScript 知道 shape 的类型是 { kind: 'square'; sideLength: number; }
    // 因此 shape.sideLength 必然是 number，不再有 'possibly undefined' 错误
    return shape.sideLength**2;
  }
  // 如果所有可能的 kind 都已处理，TypeScript 会确保这里不会被执行
  // 如果 Shape 包含更多 kind 但未在此处处理，编译器会提示错误，要求处理所有情况或提供默认值
  // 对于本例，我们可以假设所有形状都有面积
  throw new Error("Unknown shape kind provided.");
}

通过这种方式，当我们检查 shape.kind 的值时，TypeScript 能够智能地将 shape 的类型收窄到联合类型中对应的成员。例如，当 shape.kind === "circle" 为真时，编译器就知道 shape 不仅有一个 kind 属性，而且它是一个 radius 属性为 number 类型的对象。这消除了 possibly 'undefined' 的错误，并大大提高了代码的类型安全性。

鉴别联合类型的优势与应用场景

鉴别联合类型是 TypeScript 中一个非常强大的模式，它带来了多方面的好处：

1. 增强类型安全： 强制要求在特定 kind 下的属性必须存在，消除了因属性缺失或为 undefined 而导致的运行时错误。
2. 改善代码可读性： 类型定义清晰地表达了不同 kind 的对象所具有的精确结构，使代码意图一目了然。
3. 简化条件逻辑： 开发者无需再编写冗余的 Object.hasOwn 或 in 检查，可以直接访问对应属性。
4. 更好的 IDE 支持： IDE 能够根据鉴别属性的值提供更准确的自动补全和类型检查。
5. 实现穷尽性检查： 在 switch 语句中，TypeScript 可以帮助我们检查是否处理了联合类型的所有可能成员，从而避免遗漏情况。

适用场景：

• 状态管理： 定义不同状态下的数据结构，例如 LoadingState | SuccessState | ErrorState。
• 事件处理： 定义不同类型的事件对象，例如 ClickEvent | KeyboardEvent | CustomEvent。
• 配置对象： 根据配置类型加载不同的配置项。
• 解析器或转换器： 处理具有不同输入格式的数据。

总结

当在 TypeScript 中遇到基于某个判别属性而存在不同可选属性的复杂类型时，避免在单个接口中使用过多的可选属性，并依赖 Object.hasOwn 或 in 进行运行时检查。相反，应该优先考虑使用鉴别联合类型。它通过将类型拆分为更小、更具体的联合成员，并利用字面量类型的判别属性，使得 TypeScript 能够进行精确的类型收窄，从而在编译时捕获潜在的类型错误，提升代码的健壮性和可维护性。掌握这一模式是编写高质量、类型安全 TypeScript 代码的关键一步。

以上就是TypeScript 鉴别联合类型：优雅处理条件类型与可选属性的详细内容，更多请关注php中文网其它相关文章！