TypeScript基于枚举值的条件接口设计（泛型+分布式条件类型）

本文介绍如何在 TypeScript 中定义一个泛型条件接口 IGeometry，使其 shape 属性的类型严格依赖于同接口中 geometryType 的具体枚举值，实现类型安全的几何对象建模。

背景与需求

在构建地理信息系统（GIS）、图形渲染或空间数据处理类库时，一个常见的需求是：对多种几何类型（比如圆形、多边形、点、椭圆）做统一建模，同时保证每个实例的结构与类型声明完全匹配——换句话说，当 geometryType 是 CIRCLE 时，shape 必须是 ICircle，不能是 IPolygon 或其他乱七八糟的类型。TypeScript 本身并不支持“运行时值驱动编译时类型”，不过借助泛型约束 + 分布式条件类型，这活儿可以干得相当优雅。

核心思路与实现

核心思路很简单：把 geometryType 的具体值作为泛型参数 T 传入接口，然后利用条件类型（T extends X Y : Z）逐级推导 shape 的精确类型。代码一写出来，效果立竿见影：

export enum GeometryType {
  CIRCLE = 4,
  POLYGON = 5,
  POINT = 6,
  ELLIPSE = 7
}

export interface ICircle {
  center: number;
  radius: number;
}

export interface IPolygon {
  lat: number;
  lon: number;
}

export interface IPoint {
  lat: number;
  lon: number;
}

export interface IEllipse {
  yAxis: number;
  xAxis: number;
  angle: number;
}

//  条件接口：shape 类型由 geometryType 的泛型实参决定
export interface IGeometry {
  geometryType: T;
  shape: T extends GeometryType.CIRCLE
     ICircle
    : T extends GeometryType.POLYGON
     IPolygon
    : T extends GeometryType.POINT
     IPoint
    : T extends GeometryType.ELLIPSE
     IEllipse
    : never; // 防御性兜底：非法 T 值导致 shape 为 never，强制编译报错
}

用的时候，显式指定泛型参数，TypeScript 就会帮你把类型锁死：

//  正确：geometryType 和 shape 完全匹配，无类型错误
const circle: IGeometry = {
  geometryType: GeometryType.CIRCLE,
  shape: { center: 0, radius: 5 }
};

const polygon: IGeometry = {
  geometryType: GeometryType.POLYGON,
  shape: { lat: 10.0000, lon: -10.0000 }
};

//  编译错误：类型不兼容（若取消注释将触发 TS2322）
// const invalid: IGeometry = {
//   geometryType: GeometryType.CIRCLE,
//   shape: { lat: 0, lon: 0 } // Error: Type 'IPoint' is not assignable to type 'ICircle'
// };

关键注意事项

• 泛型必须显式标注（比如 IGeometry），TypeScript 通常无法从对象字面量自动推导出 T（尤其是在初始化阶段），否则 shape 会退化为联合类型 ICircle | IPolygon | ...，条件约束就白搭了；
• 如果要做运行时类型校验（比如反序列化 JSON），记得额外编写类型守卫函数（例如 isCircleGeometry(geo: IGeometry): geo is IGeometry）；
• 枚举值建议改用字符串字面量（比如 CIRCLE = "circle"），可读性和调试体验会更好，不过数字枚举也一样能用；
• 别忘了 never 分支的防御作用：当以后新增了 GeometryType 值但忘了更新条件逻辑时，shape: never 会让整个赋值直接失败，从源头堵住类型漏洞。

总结

这么一来，你就搞出了一个“一值定型”的接口契约，把类型系统变成了领域建模的主动约束工具——让错误在编码阶段暴露，而不是等到运行时崩溃。这才是类型安全该有的样子。