TypeScript中如何实现参数可选但必传其一的约束？

核心思路 #

要实现“必须且只能传入SubNodeConfig中的某一个属性”，可以通过联合类型+工具类型组合，让TypeScript在编译期就约束传入的参数只能是单个必填属性，同时禁止多传或不传。

方案一：手动定义联合类型 #

如果SubNodeConfig的属性数量固定，可以直接为每个属性生成单独的必填类型，再组合成联合类型：

// 原接口保持不变
export interface SubNodeConfig {
    alphaConfig?: AlphaConfig;
    betaConfig?: BetaConfig;
    charlieConfig?: CharlieConfig;
    deltaConfig?: DeltaConfig;
}

// 生成互斥必填的类型
type ExclusiveSubNodeConfig = 
  | Required<Pick<SubNodeConfig, 'alphaConfig'>>
  | Required<Pick<SubNodeConfig, 'betaConfig'>>
  | Required<Pick<SubNodeConfig, 'charlieConfig'>>
  | Required<Pick<SubNodeConfig, 'deltaConfig'>>;

类型说明 #

• Pick<SubNodeConfig, K>：从SubNodeConfig中提取指定属性K
• Required<T>：把类型T的所有属性设为必填
• 联合类型|：表示参数只能是其中某一种类型

方案二：通用泛型工具类型（推荐） #

如果后续SubNodeConfig可能新增属性，手动维护联合类型会很麻烦。可以写一个通用泛型，自动生成互斥必填类型：

// 通用互斥必填工具类型
type ExclusiveRequired<T> = {
  // 遍历T的每个属性K
  [K in keyof T]-?: 
    // 必填当前属性K，同时禁止其他属性存在（设为never）
    Required<Pick<T, K>> & Partial<Record<Exclude<keyof T, K>, never>>;
}[keyof T]; // 把所有遍历生成的类型转成联合类型

// 生成目标类型
type ExclusiveSubNodeConfig = ExclusiveRequired<SubNodeConfig>;

泛型细节解释 #

• [K in keyof T]-?：遍历T的所有属性，同时移除属性的可选修饰符（-?是TypeScript的映射类型修饰符）
• Partial<Record<Exclude<keyof T, K>, never>>：将除了K之外的所有属性设为never，意味着传入这些属性会直接报错
• [keyof T]：将遍历生成的对象类型转为联合类型，最终得到每个属性单独必填的互斥类型

修改业务代码 #

将getUpdated函数的updatedConfig参数类型替换为ExclusiveSubNodeConfig即可：

export interface MainNode {
    id: number;
    config: SubNodeConfig; // 如果MainNode的config也需要强制互斥，这里也可以换成ExclusiveSubNodeConfig
}

const getUpdated = (
    originalNodes: MainNode[],
    updatedConfig: ExclusiveSubNodeConfig // 替换为新类型
) => {
    const updatedNodes = [...originalNodes];
    const indexOfNodeToUpdate = 0; // 补充用户代码中缺失的索引定义
    updatedNodes[indexOfNodeToUpdate] = {
        id: 123456,
        config: updatedConfig,
    };

    return updatedNodes;
};

效果验证 #

• ✅ 合法传入：getUpdated([], { alphaConfig: {} as AlphaConfig })（仅传单个必填属性）
• ❌ 非法传入（多属性）：getUpdated([], { alphaConfig: {}, betaConfig: {} })（TypeScript会直接报错）
• ❌ 非法传入（空对象）：getUpdated([], {})（TypeScript会直接报错）

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