TypeScript用户定义类型守卫导致交叉类型问题

嘿，我明白你遇到的困惑了——用Symbol做类型守卫却没得到预期的类型收窄，反而出现了Data & CustomError这种奇怪的交叉类型，这确实挺挠头的。咱们一步步拆解问题，找到原因和解决方案。

首先，还原你的代码场景（补全未写完的部分） #

我猜你的代码大概是这样的：

const FailureSymbol = Symbol('Failure');
const SuccessSymbol = Symbol('Success');

interface IFailure {
  symbol: typeof FailureSymbol;
  error: CustomError;
}

interface ISuccess<T> {
  symbol: typeof SuccessSymbol;
  data: T;
}

type Either<T> = ISuccess<T> | IFailure;

// 你的用户定义类型守卫
function isFailure<T>(either: Either<T>): either is IFailure {
  return either.symbol === FailureSymbol;
}

// 使用时出现问题的地方
type Data = { id: number; name: string };
class CustomError extends Error {}

const maybeEither: Either<Data> = Math.random() > 0.5 
  ? { symbol: SuccessSymbol, data: { id: 1, name: 'test' } } 
  : { symbol: FailureSymbol, error: new CustomError('oops') };

if (isFailure(maybeEither)) {
  // 你预期maybeEither是IFailure，但TypeScript推断成了Data & CustomError？
  console.log(maybeEither.error); // 可能还会报错？
}

为什么会出现交叉类型的推断？ #

这种情况通常是因为TypeScript无法明确区分联合类型的两个分支，导致它只能保留所有分支的公共属性和可能的交集。常见的原因有两个：

1. 判别式属性的类型定义不严谨：如果你的ISuccess和IFailure中的symbol属性没有被TypeScript识别为互斥的字面量类型，它就无法通过类型守卫完成精确收窄。比如，如果你不小心把ISuccess的symbol类型写成了Symbol而不是typeof SuccessSymbol，TypeScript会认为两个分支的symbol可能有重叠，从而无法排除另一个分支的类型。
2. 变量的初始类型注解有误：如果maybeEither的类型被错误地注解成了ISuccess<Data> & IFailure（交叉类型）而不是联合类型，那类型守卫自然没法帮你收窄到单一分支。

正确的实现方式 #

要让TypeScript正确识别互斥的联合分支，我们需要确保判别式属性是唯一且可区分的字面量类型。用Symbol做判别式完全没问题，关键是要把类型定义写严谨：

方案1：用Symbol作为属性名（更简洁）

// 定义唯一的Symbol作为分支标识
const isSuccess = Symbol('isSuccess');
const isFailure = Symbol('isFailure');

// 成功分支：用Symbol作为属性，值为true（字面量类型）
interface Success<T> {
  [isSuccess]: true;
  data: T;
}

// 失败分支：同理
interface Failure {
  [isFailure]: true;
  error: CustomError;
}

type Either<T> = Success<T> | Failure;

// 类型守卫：检查Symbol属性是否存在
function isFailureResult<T>(either: Either<T>): either is Failure {
  return isFailure in either;
}

// 使用示例
const result: Either<Data> = Math.random() > 0.5
  ? { [isSuccess]: true, data: { id: 1, name: 'test' } }
  : { [isFailure]: true, error: new CustomError('failed') };

if (isFailureResult(result)) {
  // 这里TypeScript会正确推断result为Failure类型
  console.log(result.error.message);
} else {
  // 这里推断为Success<Data>
  console.log(result.data.name);
}

方案2：用Symbol作为属性值（更直观）

如果你更习惯用type或symbol属性来标识分支，确保属性的类型是具体的Symbol字面量：

const SuccessType = Symbol('Success');
const FailureType = Symbol('Failure');

interface Success<T> {
  type: typeof SuccessType;
  data: T;
}

interface Failure {
  type: typeof FailureType;
  error: CustomError;
}

type Either<T> = Success<T> | Failure;

function isFailure<T>(either: Either<T>): either is Failure {
  return either.type === FailureType;
}

// 使用时，TypeScript能完美区分两个分支
const result: Either<Data> = Math.random() > 0.5
  ? { type: SuccessType, data: { id: 1, name: 'test' } }
  : { type: FailureType, error: new CustomError('oops') };

if (isFailure(result)) {
  result.error; // 正确识别为CustomError
} else {
  result.data; // 正确识别为Data
}

关键要点总结 #

• 确保联合类型的每个分支都有互斥的判别式属性，且属性的类型是具体的字面量（比如typeof SuccessSymbol而不是Symbol）。
• 类型守卫的返回类型谓词（either is Failure）必须严格对应联合类型中的某个分支，不能有歧义。
• 如果还是有问题，可以用TypeScript的typeof操作符打印变量的类型，检查是否有意外的交叉类型混入。

内容的提问来源于stack exchange，提问作者Jesse Carter