TypeScript联合与交叉类型报错不直观且错误，如何优化？

我定义的导出类型Animal逻辑校验规则正确，但TypeScript给出了错误的校验提示：

export type Animal = RequireSwimOrFly & RequireColorOrSizeOrVolume & (CantHaveBothColorOrSize | CanHaveNeitherColorOrSize)

const myAnimal: Animal = {
  swim: "greatly",
  color: "yellow",
  size: "large",
}

得到的错误提示：

Property 'fly' is missing in type '{ swim: string; color: string; size: string; }' but required in type 'Required<Pick<IAnimal, "fly">>'.(2322)

但真实错误是同时存在color和size，而非缺少fly。

现有类型定义 #

基础接口：

interface IAnimal {
    swim?: string;
    fly?: string;
    color?: string;
    size?: string;
    volume?: string;
}

校验类型：

type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
    Pick<T, Exclude<keyof T, Keys>>
    & {
        [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>
    }[Keys]

type RequireOnlyOne<T, Keys extends keyof T = keyof T> =
    Pick<T, Exclude<keyof T, Keys>>
    & {
        [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, undefined>>
    }[Keys]

组合校验类型：

type RequireSwimOrFly = RequireAtLeastOne<IAnimal, 'swim' | 'fly'>
type RequireColorOrSizeOrVolume = RequireAtLeastOne<IAnimal, 'color' | 'size' | 'volume'>
type CantHaveBothColorOrSize = RequireOnlyOne<IAnimal, 'color' | 'size'>
type CanHaveNeitherColorOrSize = Omit<IAnimal, 'color' | 'size'> & { color?: never, size?: never }

问题原因 #

TypeScript在处理交叉+联合类型时，类型检查器会尝试匹配联合类型的分支。当myAnimal既不符合CantHaveBothColorOrSize（同时存在color和size），也不符合CanHaveNeitherColorOrSize（存在color/size）时，会回溯到前面的RequireSwimOrFly类型，尝试匹配其某个分支（比如要求fly必须存在的分支），从而抛出偏离实际问题的错误提示。

解决方案：优化类型结构，让冲突优先被检测 #

调整Animal类型的结构，将颜色/尺寸相关的约束合并为更明确的联合类型，确保类型检查器优先检测color和size的冲突：

type Animal = RequireSwimOrFly & (
  // 情况1：只有color或只有size（自动满足至少一个color/size/volume）
  RequireOnlyOne<IAnimal, 'color' | 'size'>
  // 情况2：没有color和size，但必须有volume（满足至少一个color/size/volume）
  | (Omit<IAnimal, 'color' | 'size'> & Required<Pick<IAnimal, 'volume'>>)
);

修改后，当同时传入color和size时，TypeScript会直接提示：

Type '{ swim: string; color: string; size: string; }' is not assignable to type 'Animal'.
Type '{ swim: string; color: string; size: string; }' is not assignable to type 'RequireOnlyOne<IAnimal, "color" | "size">'.
Types of property 'size' are incompatible.
Type 'string' is not assignable to type 'undefined'.(2322)

这个提示直接指向了size属性的问题，开发者能直观理解是同时存在color和size导致的错误。

额外优化：自定义错误提示（可选） #

如果需要更直白的提示，可以利用TypeScript的条件类型和never添加自定义错误信息：

type CheckNoBothColorAndSize<T> = T extends { color: string; size: string } 
  ? never & { __ERROR__: "Cannot have both color and size properties" } 
  : T;

type Animal = CheckNoBothColorAndSize<RequireSwimOrFly & RequireColorOrSizeOrVolume>;

此时错误提示会包含自定义说明：

Type '{ swim: string; color: string; size: string; }' is not assignable to type 'Animal'.
Type '{ swim: string; color: string; size: string; }' is not assignable to type 'never & { ERROR: "Cannot have both color and size properties"; }'.(2322)

这种方式能让开发者一眼看清错误原因。

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