TypeScript：如何解决重叠但不兼容字符串联合类型的混淆问题

背景 #

有两个字符串联合类型，各包含100+取值，部分取值重叠但用途完全不同：

• NodeTypes：用于定义视图模型对象的类型
• ContentTypes：用于定义API返回内容的type字段取值

type NodeTypes = 
 | 'PRO_TERM'
 | 'THEME'
 | 'REFERENCE'
 // ...其他100+取值
;

type ContentTypes = 
 | 'TERM'
 | 'THEME'
 | 'REFERENCE'
 // ...其他100+取值
;

现有问题 #

当混用两个类型时，TypeScript不会抛出预期的错误，比如：

const someItems: NodeTypes[] = ['PRO_TERM', 'THEME'];
const otherItems: ContentTypes[] = ['TERM', 'THEME', ...];
const test = someItems.includes(otherItems[0]); // TS应报错但未报错

尝试的方案及新问题 #

尝试用**品牌类型（Branded Type）**解决类型混用问题，实现如下：

const nodeTypes = [
 'PRO_TERM',
 'THEME',
 'REFERENCE',
 // ...其他取值
] as const;

export type NodeType = (typeof nodeTypes)[number] & { __brand: 'NodeType' };

export const NODETYPES = Object.fromEntries(nodeTypes.map((type) => [type, type])) as {
  [K in (typeof nodeTypes)[number]]: K & { __brand: 'NodeType' };
};

对ContentTypes做同样处理后，虽然避免了类型混用，但丢失了原本的类型推断能力：

原代码（类型推断正常） #

type ProTermNode = BasicNode & {
 type: 'PRO_TERM'
}
type ContentNode = ProTermNode | ThemeNode | /* ...其他节点类型 */;
const node: ContentNode = {...};
if (node.type === 'PRO_TERM') {
 // node自动推断为ProTermNode
}

改为品牌类型后（类型推断失效） #

type ProTermNode = BasicNode & {
 type: typeof NODETYPES.PRO_TERM;
}
const node: ContentNode = {...};
if (node.type === NODETYPES.PRO_TERM) {
 // node仍被推断为ContentNode，无法自动窄化
}

更优实现方案 #

可以通过保留字面量特征的品牌类型来解决，既阻止类型混用，又保留类型推断能力。

步骤1：创建带品牌的字面量工具函数 #

// 工具函数：生成带品牌标记的字面量类型
function createBrandedLiteral<T extends string>(value: T, brand: string): T & { __brand: typeof brand } {
  return value as T & { __brand: typeof brand };
}

步骤2：定义带品牌的常量和类型 #

针对NodeTypes和ContentTypes分别生成带品牌的常量集合和对应的类型：

// NodeType相关定义
export const NODE_TYPES = {
  PRO_TERM: createBrandedLiteral('PRO_TERM', 'NodeType'),
  THEME: createBrandedLiteral('THEME', 'NodeType'),
  REFERENCE: createBrandedLiteral('REFERENCE', 'NodeType'),
  // ...其他100+取值
} as const;

export type NodeType = typeof NODE_TYPES[keyof typeof NODE_TYPES];

// ContentType相关定义
export const CONTENT_TYPES = {
  TERM: createBrandedLiteral('TERM', 'ContentType'),
  THEME: createBrandedLiteral('THEME', 'ContentType'),
  REFERENCE: createBrandedLiteral('REFERENCE', 'ContentType'),
  // ...其他100+取值
} as const;

export type ContentType = typeof CONTENT_TYPES[keyof typeof CONTENT_TYPES];

步骤3：使用带品牌的类型定义节点 #

type BasicNode = {
  // 基础节点属性，比如id、name等
};

type ProTermNode = BasicNode & {
  type: typeof NODE_TYPES.PRO_TERM;
  // ProTermNode专属属性
};

type ThemeNode = BasicNode & {
  type: typeof NODE_TYPES.THEME;
  // ThemeNode专属属性
};

type ContentNode = ProTermNode | ThemeNode /* | 其他节点类型 */;

步骤4：验证效果 #

1. 阻止类型混用：

const someItems: NodeType[] = [NODE_TYPES.PRO_TERM, NODE_TYPES.THEME];
const otherItems: ContentType[] = [CONTENT_TYPES.TERM, CONTENT_TYPES.THEME];
const test = someItems.includes(otherItems[0]); // TS报错，符合预期

2. 保留类型推断：

const node: ContentNode = { 
  type: NODE_TYPES.PRO_TERM,
  // 其他属性
};

if (node.type === NODE_TYPES.PRO_TERM) {
  // node自动推断为ProTermNode，可访问专属属性
  console.log(node.proTermSpecificProp); // 无类型错误
}

原理说明 #

每个带品牌的常量（比如NODE_TYPES.PRO_TERM）的类型是'PRO_TERM' & { __brand: 'NodeType' }，TypeScript会同时识别字面量'PRO_TERM'和品牌标记：

• 品牌标记用于区分NodeType和ContentType，阻止混用
• 字面量特征保留了可辨识联合的类型窄化能力，确保条件判断时能自动推断具体节点类型

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