TypeScript类型安全：利用判别式联合处理可选属性的“可能未定义”错误

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

TypeScript类型安全：利用判别式联合处理可选属性的“可能未定义”错误

2025-11-09

浏览次数：次

返回列表

typescript类型安全：利用判别式联合处理可选属性的“可能未定义”错误

本文深入探讨了在TypeScript中处理具有可选属性的联合类型时，如何有效解决“属性可能未定义”的常见错误。我们将分析为何简单的属性存在性检查不足以满足类型安全要求，并详细介绍如何通过引入判别式联合（Discriminated Unions）这一强大模式，来构建更健壮、类型更明确的代码结构，从而消除不必要的类型断言，提升代码的可读性和可维护性。

理解TypeScript中可选属性的类型推断挑战

在TypeScript中，当我们定义一个接口并使其某些属性为可选时（例如使用 ? 符号），这意味着该属性可能存在，也可能不存在。如果存在，它的类型是定义的类型；如果不存在，它就是 undefined。这种灵活性在某些场景下非常有用，但当我们需要根据一个共享的“种类”属性来判断并访问特定属性时，就会遇到类型推断上的挑战。

考虑以下一个几何图形接口的示例：

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;
}

在这个 getArea 函数中，尽管我们使用了 Object.hasOwn(shape, "radius") 或 "sideLength" in shape 来检查属性是否存在，TypeScript 编译器仍然会报错 ts(18048): 'shape.radius' is possibly 'undefined'.。这是因为，从 Shape 接口的定义来看，radius 和 sideLength 属性的类型被声明为 number | undefined。即使 Object.hasOwn 确认了属性的存在，TypeScript 的类型系统并不能仅凭运行时检查就自动将 shape.radius 的类型从 number | undefined 精确地收窄为 number。它只知道这个属性可能存在，但其值仍然可以是 undefined，因为它在接口中被明确标记为可选。

这种行为反映了TypeScript在处理结构化类型时的严谨性：它依赖于声明的类型定义，而非运行时可能存在的属性。

解决方案：利用判别式联合（Discriminated Unions）

解决上述问题的最佳实践是采用判别式联合（Discriminated Unions）。判别式联合是一种强大的模式，它通过一个具有字面量类型的公共属性（即判别式，discriminant），来区分联合类型中的不同成员。每个成员都明确定义了它所拥有的属性，从而允许TypeScript进行更精确的类型推断。

我们将 Shape 接口重构为判别式联合类型：

火龙果写作

用火龙果，轻松写作，通过校对、改写、扩展等功能实现高质量内容生产。

277 查看详情火龙果写作

type Shape =
  | {
      kind: 'circle';
      radius: number; // 明确要求圆形必须有 radius
    }
  | {
      kind: 'square';
      sideLength: number; // 明确要求正方形必须有 sideLength
    };

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

kind 属性是判别式，它在每个联合成员中都有一个唯一的字面量类型（'circle' 或 'square'）。
当 kind 是 'circle' 时，radius 属性是必需的 number 类型。
当 kind 是 'square' 时，sideLength 属性是必需的 number 类型。

这样一来，TypeScript 的控制流分析能力就能发挥作用。当我们在 if (shape.kind === "circle") 这样的条件语句中检查 kind 属性时，TypeScript 会自动将 shape 的类型收窄为 { kind: 'circle'; radius: number; }。此时，shape.radius 将被安全地推断为 number 类型，从而消除了“可能未定义”的错误。

重构 getArea 函数

使用判别式联合后，getArea 函数可以被重构为更简洁、类型更安全的形式：

function getArea(shape: Shape): number { // 返回类型不再需要 | undefined
  if (shape.kind === "circle") {
    // 在这里，TypeScript 已经知道 shape 是 { kind: 'circle'; radius: number; }
    // 因此 shape.radius 被安全地推断为 number
    return Math.PI * shape.radius**2;
  }
  else { // 此时 shape.kind 必然是 "square"
    // TypeScript 知道 shape 是 { kind: 'square'; sideLength: number; }
    // 因此 shape.sideLength 被安全地推断为 number
    return shape.sideLength**2;
  }
}

// 示例调用
const circle: Shape = { kind: 'circle', radius: 10 };
const square: Shape = { kind: 'square', sideLength: 5 };

console.log("Circle Area:", getArea(circle)); // 输出: Circle Area: 314.1592653589793
console.log("Square Area:", getArea(square)); // 输出: Square Area: 25

在这个重构后的 getArea 函数中：