TypeScript类属性联合类型不符合预期问题排查

问题根源 #

TypeScript 对类实例属性的类型推断逻辑与独立变量不同：当联合类型作为类属性时，TS 默认不会自动收窄到具体子类型（即便运行时它是 Resolvable<M> 实例），而独立变量可通过上下文自动收窄，导致属性无法直接访问 resolve()、raw、val 成员。

可行方案 #

1. 类型谓词（Type Predicate）做精准收窄 #

定义类型守卫函数，一次性解决所有属性的类型判断，避免重复使用类型断言：

// 类型守卫：判断值是否为 Resolvable 实例
function isResolvable<T>(value: unknown): value is Resolvable<T> {
  return typeof value === 'object' && value !== null && 
         'resolve' in value && 'raw' in value && 'val' in value;
}

// 使用示例
const model = new ModelB();
if (isResolvable(model.a)) {
  model.a.resolve(); // TS 自动识别类型，无报错
  console.log(model.a.raw, model.a.val);
}

遍历数组时可结合 filter 批量收窄：

const resolvedItems = model.arrayProp.filter(isResolvable);
resolvedItems.forEach(item => item.resolve());

2. 调整 ResolvableProxy 类型定义，暴露公共成员 #

修改联合类型，让 resolve()、raw、val 作为可选公共成员存在，避免类型冲突：

// 调整后的联合类型
type ResolvableProxy<M> = M | (Resolvable<M> & {
  resolve?: () => void;
  raw?: M;
  val?: M;
});

这样即便 TS 未收窄类型，也能安全访问这些可选成员（需注意空值判断）。

3. 类属性装饰器增强类型推断 #

借助装饰器为类属性注入更精确的类型提示，需依赖 reflect-metadata：

import 'reflect-metadata';

// 自定义装饰器，标记属性为 Resolvable 类型
function ResolvableProp(): PropertyDecorator {
  return (target, propKey) => {
    // 利用元数据辅助 TS 类型推断
    const type = Reflect.getMetadata('design:type', target, propKey);
    // 可添加额外元数据逻辑
  };
}

// 使用装饰器
class ModelB {
  @ResolvableProp()
  a: ResolvableProxy<string>;
}

需在 tsconfig.json 中开启 emitDecoratorMetadata 和 experimentalDecorators。

4. 带序列化兼容的 getter/setter 方案 #

如果之前的显式 get/set 导致序列化问题，重写 toJSON() 方法保证输出正确值：

class ModelB {
  private _a: ResolvableProxy<string>;

  // getter 直接返回 Resolvable 类型，解决访问问题
  get a(): Resolvable<string> {
    return this._a as Resolvable<string>;
  }

  set a(value: string | Resolvable<string>) {
    this._a = value;
  }

  // 重写 toJSON，序列化时输出原始值或解析后的值
  toJSON() {
    const json = { ...this };
    json.a = this._a instanceof Resolvable ? this._a.val : this._a;
    return json;
  }
}

此方案既解决类型访问问题，又避免 JSON 序列化时包含包装器的冗余属性。

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