如何在TypeScript中模拟标称类型？解决参数类型混淆问题

我太懂这种烦恼了——明明是两种语义完全不同的数值，却都用number来表示，哪怕给参数起了index/cursorPos这种名字，时间久了或者团队协作时还是容易传混，编译阶段根本拦不住。既然TypeScript是结构类型系统，没法原生区分这两种"语义不同的number"，咱们可以用下面两种方案来实现标称类型的效果：

方案一：品牌类型（Branded Types）—— 轻量无运行时开销 #

这是TypeScript社区里模拟标称类型的主流方案，核心思路是给普通number加上一个编译时的"品牌标记"，运行时还是纯数值，完全没有额外开销。

实现代码 #

// 定义带品牌标记的类型，unique symbol确保两个类型完全不兼容
type ArrayIndex = number & { readonly __brand: unique symbol };
type CursorPosition = number & { readonly __brand: unique symbol };

// 提供类型转换函数，同时做业务规则校验
const toArrayIndex = (n: number): ArrayIndex => {
  if (!Number.isInteger(n) || n < 0) {
    throw new Error(`无效的数组索引：${n}，必须是非负整数`);
  }
  return n as ArrayIndex;
};

const toCursorPosition = (n: number): CursorPosition => {
  if (!Number.isInteger(n) || n < 0) {
    throw new Error(`无效的光标位置：${n}，必须是非负整数`);
  }
  return n as CursorPosition;
};

使用示例 #

现在你可以给函数明确指定参数类型，编译阶段就会拦截错误的传入：

const demoArr = ["a", "b", "c"];

// 仅接受数组索引的函数
function getArrayItem(arr: string[], index: ArrayIndex): string {
  return arr[index];
}

// 仅接受光标位置的函数
function insertAtCursor(arr: string[], pos: CursorPosition, val: string): string[] {
  return [...arr.slice(0, pos), val, ...arr.slice(pos)];
}

// ✅ 合法调用
getArrayItem(demoArr, toArrayIndex(1)); // 返回 "b"
insertAtCursor(demoArr, toCursorPosition(3), "d"); // 返回 ["a","b","c","d"]

// ❌ 编译报错：类型不匹配，直接拦在开发阶段
getArrayItem(demoArr, toCursorPosition(3));
insertAtCursor(demoArr, toArrayIndex(1), "x");

这种方案的好处是：既保证了类型安全，又不会给运行时增加任何负担，还能在转换函数里提前校验数值的合法性，避免后续出现越界等问题。

方案二：装箱方案—— 更直观但有运行时开销 #

如果你觉得品牌类型的"类型断言"有点不直观，也可以用类来包装数值，实现强类型区分：

实现代码 #

class ArrayIndex {
  constructor(public readonly value: number) {
    if (!Number.isInteger(value) || value < 0) {
      throw new Error(`无效的数组索引：${value}`);
    }
  }
}

class CursorPosition {
  constructor(public readonly value: number) {
    if (!Number.isInteger(value) || value < 0) {
      throw new Error(`无效的光标位置：${value}`);
    }
  }
}

使用示例 #

function getItem(arr: string[], index: ArrayIndex) {
  return arr[index.value];
}

// ✅ 合法调用
getItem(demoArr, new ArrayIndex(0));

// ❌ 编译报错
getItem(demoArr, new CursorPosition(0));

这种方案的优点是语义更清晰，新手更容易理解，但缺点是每次创建都会生成一个对象，带来微小的运行时开销，适合对性能要求不高但追求代码可读性的场景。

总结 #

如果想平衡类型安全和性能，优先选品牌类型；如果团队更看重代码直观性，不在乎那点运行时开销，装箱方案也是不错的选择。两种方案都能彻底解决你说的参数混淆问题，把错误提前拦在编译阶段。

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