TypeScript泛型约束：限定参数为单一类型而非Union Types

你碰到的这个需求其实挺典型的——咱们想要泛型参数只能是string或number里的某一种单独类型，而不是它们的联合类型string | number。直接用联合类型约束的话，TypeScript确实会允许传入联合类型，所以得用点小技巧来实现这个限制。下面给你几个实用的思路：

1. 用条件类型排除联合类型 #

我们可以通过条件类型来检测泛型参数是不是联合类型，如果是就返回never来禁用它，同时保留单一的string或number类型：

type SingleStringOrNumber<T> = 
  T extends string | number 
    ? (string extends T ? never : number extends T ? never : T)
    : never;

// 示例函数
function getValue<TKey extends SingleStringOrNumber<TKey>>(key: TKey, obj: Record<TKey, any>) {
  return obj[key];
}

// 合法调用：传入单一string
getValue("name", { name: "Alice" });
// 合法调用：传入单一number
getValue(1, { 1: "one" });

// 类型错误：不能传入联合类型string | number
getValue(Math.random() > 0.5 ? "name" : 1, { name: "Alice", 1: "one" });

这里的逻辑很简单：如果TKey是string | number这种联合类型，那么string extends TKey和number extends TKey都会返回true，最终类型会变成never，直接触发类型错误；而如果TKey是单一的string或number，只会满足其中一个分支，保留原类型。

2. 函数重载（适合函数场景） #

如果你的需求是针对函数的（比如你提到的处理string或StructuredText的转换函数），函数重载是更直观的方案——直接为每种允许的类型单独定义重载：

// 先定义StructuredText类型（根据你的需求模拟）
type StructuredText = { content: string[] };

// 重载定义：分别处理string和StructuredText类型
function transformText(text: string): string;
function transformText(text: StructuredText): string;
// 实际实现函数
function transformText(text: string | StructuredText): string {
  if (typeof text === "string") {
    // 处理普通字符串的逻辑，比如转大写
    return text.toUpperCase();
  } else {
    // 处理StructuredText的逻辑，比如拼接内容
    return text.content.join(" ");
  }
}

// 合法调用：传入string
transformText("hello world");
// 合法调用：传入StructuredText
transformText({ content: ["Hello", "from", "StructuredText"] });

// 类型错误：不能传入联合类型
transformText(Math.random() > 0.5 ? "hello" : { content: ["World"] });

这种方式可读性极强，每种类型的处理逻辑也能在实现里清晰区分，完美匹配你提到的文本转换场景。

3. 进阶：利用泛型分配特性 #

还有一种更简洁的写法，利用TypeScript泛型的分配条件类型特性，检测类型是否为单一类型：

type EnsureSingle<T, U> = T extends U ? ([U] extends [T] ? never : T) : never;

function processKey<TKey extends EnsureSingle<TKey, string | number>>(key: TKey) {
  // 这里可以写你的业务逻辑
  console.log(`Processing key: ${key}`);
}

// 合法调用
processKey("id");
processKey(100);

// 类型错误
processKey(Math.random() > 0.5 ? "id" : 100);

这个思路的核心是：如果TKey是联合类型，[U] extends [T]会返回true（因为U是string | number，和联合类型的TKey一致），所以返回never；如果是单一类型，[U] extends [T]会返回false，从而保留原类型。

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