如何在TypeScript中限制函数仅接受显式合法泛型调用？

问题根源 #

当前代码存在两个核心问题导致约束失效：

1. 结构类型兼容：TypeScript采用结构类型系统，空接口IXpto和IBase因无属性差异被判定为兼容，即使没有显式继承关系。
2. 自动泛型推断：未指定泛型时，TypeScript会自动推断T为IBase，绕过了显式指定的要求。

解决方案 #

1. 给IBase添加品牌属性，区分显式继承类型 #

通过唯一符号属性标记IBase，确保只有显式继承它的类型才能通过约束：

// 定义唯一品牌符号，避免被意外实现
const baseBrand = Symbol('IBaseBrand');

// 修改IBase接口，添加必选品牌属性
interface IBase {
  [baseBrand]: true;
}

// 显式继承IBase的接口自动继承品牌属性
interface ICorge extends IBase {}

// IXpto无品牌属性，无法兼容IBase约束
interface IXpto {}

2. 强制显式指定泛型参数 #

将泛型参数默认值设为never，并通过条件类型让未指定泛型的调用直接报错：

import { useState, useEffect } from 'react';

// 假设getJson是已定义的异步函数
declare function getJson(path: string): Promise<unknown>;

export default function useLoadData<T extends IBase = never>(
  path: string
): T extends never ? never : { entities: T[]; isLoading: boolean } {
  const [entities, setEntities] = useState<T[]>([]);
  const [isLoading, setIsLoading] = useState<boolean>(true);

  useEffect(() => {
    loadData();
  }, []);

  async function loadData() {
    setIsLoading(true);
    try {
      const data = await getJson(path);
      setEntities(data as T[]);
    } finally {
      setIsLoading(false);
    }
  }

  return { entities, isLoading } as ReturnType<typeof useLoadData<T>>;
}

验证效果 #

• 合法调用：完全符合约束，正常通过检查

  const { entities } = useLoadData<ICorge>("ghi"); // ✅ 无报错
  

• 未指定泛型：调用时直接报错，返回类型为never

  const { entities1 } = useLoadData("abc"); // ❌ 报错：类型"never"不存在属性"entities1"
  

• 传入非法泛型：泛型不满足IBase约束，直接报错

  const { entities2 } = useLoadData<IXpto>("def"); // ❌ 报错：类型"IXpto"不满足约束"IBase"
  

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