本文介绍 TypeScript 中因结构化类型系统导致抽象基类子类被误认为可互换的问题，并通过“类型标记（branding）”技术实现严格的类型区分，确保 UserId 和 OrganizationId 等语义不同的 ID 类型不可相互替代。
本文介绍 typescript 中因结构化类型系统导致抽象基类子类被误认为可互换的问题，并通过“类型标记（branding）”技术实现严格的类型区分，确保 `userid` 和 `organizationid` 等语义不同的 id 类型不可相互替代。
在 TypeScript 的结构化类型系统中，只要两个类型的成员结构完全兼容（即具有相同的公共属性和方法签名），它们就被视为可互换——即使它们语义上截然不同。这在基于抽象基类建模领域实体（如各类 ID）时可能引发隐蔽的类型安全问题。
例如，以下代码看似合理，实则存在严重类型漏洞：
abstract class Id {
public abstract getPrefix(): string;
}
class UserId extends Id {
public getPrefix(): string { return 'user'; }
}
class OrganizationId extends Id {
public getPrefix(): string { return 'organization'; }
}
const getUser = (id: UserId) => console.log(`Fetching user: ${id.getPrefix()}`);
const userId = new UserId();
const orgId = new OrganizationId();
getUser(userId); // ✅ 正确
getUser(orgId); // ❌ 意外通过！但逻辑上绝不应允许尽管 UserId 和 OrganizationId 代表完全不同的业务概念，TypeScript 仍会接受 getUser(orgId)，因为二者都满足 Id 的结构要求（仅含 getPrefix(): string），且无其他差异化字段。这种“过度兼容”违背了类型系统的初衷：用编译期检查保障运行时语义正确性。
解决方案：私有字段标记（Private Branding）
核心思路是为每个具体子类引入唯一、不可继承、不可赋值的私有字段，利用 TypeScript 对 private 成员的严格访问控制规则（即 private 字段仅在声明它的类内部可见，且不同类的 private 字段互不兼容）来打破结构等价性。
✅ 推荐实现如下：
abstract class Id {
private readonly _brand!: void; // 唯一标识基类，不可被子类继承覆盖
public abstract getPrefix(): string;
}
class UserId extends Id {
private readonly _brand!: void; // 显式声明，与基类同名但属不同私有空间
public getPrefix(): string {
return 'user';
}
}
class OrganizationId extends Id {
private readonly _brand!: void;
public getPrefix(): string {
return 'organization';
}
}此时，UserId 和 OrganizationId 的实例类型不再兼容：
- UserId 包含其独有的 private _brand；
- OrganizationId 包含另一个独立的 private _brand；
- TypeScript 将二者视为完全不同的名义类型（nominal-like），即使结构相同也无法赋值或传参。
再次调用 getUser(orgId) 时，编译器将精准报错：
Argument of type 'OrganizationId' is not assignable to parameter of type 'UserId'. Types have separate declarations of a private property '_brand'.
注意事项与最佳实践
- 字段必须为 private：protected 或 public 无法达成隔离效果，因子类可继承/覆盖；readonly 非必需但推荐，强调不可变性。
- 类型标注 ! 是安全的：_brand!: void 使用非空断言，因该字段仅用于类型标记，无需实际初始化，也不会被访问。
- 避免滥用：仅在确实需要语义隔离（而非单纯结构约束）的场景使用，如 ID 类型、状态枚举包装、领域模型标识等。
- 与 unique symbol 对比：更轻量级，无需额外 symbol 声明；但若需跨模块强唯一性，可考虑 unique symbol + private 组合。
通过这一模式，你能在保留抽象基类共性定义的同时，强制 TypeScript 尊重业务语义边界——让类型系统真正成为你领域模型的守护者。
