Skip to content

品牌类型混淆:与幻影属性的交集

快速摘要

你使用了品牌类型(string & { __brand: 'X' })但未正确构造品牌 —— 幻影属性在运行时不存在。

为什么发生

  • 品牌类型通过类型断言创建,没有验证值的构造函数

  • 幻影品牌属性在编译时检查但在运行时不存在,导致混淆

  • 两个具有相同底层类型的品牌类型因品牌未在运行时强制而混淆

最小示例

✗ 错误代码
type UserId = string & { __brand: 'UserId' };
const id = 'not-a-uuid' as UserId; // no validation!
function getUser(id: UserId) { /* ... */ }
getUser(id); // accepts invalid ID
✓ 修复代码
type UserId = string & { __brand: 'UserId' };
function makeUserId(s: string): UserId {
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(s)) {
    throw new Error('Invalid UUID');
  }
  return s as UserId;
}
const id = makeUserId('550e8400-e29b-41d4-a716-446655440000'); // validated

工厂函数在转换为品牌类型前验证字符串是正确的 UUID,确保运行时安全与编译时类型安全并存。

如何诊断

  • 检查品牌值是否通过正确的构造函数创建而非仅类型断言

  • 在构造函数中使用运行时检查(如 UUID 正则)验证值匹配品牌

  • 在运行时记录品牌值确认它只是底层原始类型没有幻影属性

如何修复

  • 创建验证值并转换为品牌类型的工厂函数:function makeUserId(s: string): UserId

  • 在工厂函数中添加运行时验证确保值满足品牌要求

  • 使用带私有构造函数的基于类的品牌类型,防止不经验证的直接实例化

如何预防

  • 始终通过验证的工厂函数创建品牌类型,永远不通过原始类型断言

  • 在工厂中添加运行时验证确保值匹配品牌的语义要求

相关资源

相关课程

← 返回语言