本文介绍 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 尊重业务语义边界——让类型系统真正成为你领域模型的守护者。