17370845950

本文介绍在 typescript 中如何让泛型函数根据输入对象的 `type` 字段（判别联合）自动推导并返回精确匹配的输出类型，解决 `switch` 分支内类型无法被正确收窄的核心问题。

在 TypeSc

ript 类型系统中，当函数需根据输入对象的判别属性（如 type: "circle"）返回不同结构的类型时，单纯依赖泛型约束和 switch 语句往往会导致编译错误——分支内部的返回值无法被 TypeScript 自动收窄为泛型所期望的精确子类型。这是因为 TypeScript 的控制流分析（control flow analysis）对泛型参数 TShape 在 switch 块内的细化能力有限，v1Shape 在 case "circle" 中仍被视为 TShape（即 CircleV1 | SquareV1），而非确定的 CircleV1，导致 { ...v1Shape, sides: 1 } 无法被安全赋值给 Extract

✅ 推荐方案：辅助函数 + 显式类型映射 + 类型断言（安全）

最简洁、可维护且兼容性强的解法是 分离类型推导与运行时逻辑：

• 定义一个明确的类型映射工具类型 ConvertedToV2，直接根据 T["type"] 分支返回对应 V2 类型；
• 实现一个非泛型的辅助函数 convertToV2_helper，它接收宽泛的 ShapeV1 并返回宽泛的 ShapeV2，利用 switch 的完整判别联合支持完成类型安全的构造；
• 主函数 convertToV2 调用该辅助函数，并通过 as ConvertedToV2 进行受控类型断言——由于映射关系完全由开发者定义且辅助函数已确保逻辑完备，该断言是类型安全的。

type CircleV1 = { type: "circle"; colour: string };
type CircleV2 = { type: "circle"; colour: string; sides: 1 };
type SquareV1 = { type: "square"; colour: string };
type SquareV2 = { type: "square"; colour: string; sides: 4 };

type ShapeV1 = CircleV1 | SquareV1;
type ShapeV2 = CircleV2 | SquareV2;

// ? 核心：显式、可读的类型映射
type ConvertedToV2 = 
  T["type"] extends "circle" ? CircleV2 : 
  T["type"] extends "square" ? SquareV2 : 
  never;

function convertToV2(v1Shape: T): ConvertedToV2 {
  // ✅ 辅助函数：在宽泛类型上做完整判别，无泛型干扰
  function convertToV2_helper(shape: ShapeV1): ShapeV2 {
    switch (shape.type) {
      case "circle":
        return { ...shape, sides: 1 }; // ✅ 类型检查通过：CircleV1 → CircleV2
      case "square":
        return { ...shape, sides: 4 }; // ✅ 类型检查通过：SquareV1 → SquareV2
    }
  }

  // ✅ 安全断言：映射逻辑与实现逻辑严格一致
  return convertToV2_helper(v1Shape) as ConvertedToV2;
}

// ✅ 调用端获得完美类型推导
const circleV2 = convertToV2({ type: "circle", colour: "red" });
//    ^? CircleV2 —— 具备智能提示、不可写 `sides: 4`
const squareV2 = convertToV2({ type: "square", colour: "blue" });
//    ^? SquareV2

✅ 进阶方案：函数重载（更直观，TS ≥ 4.9 推荐）

若项目使用 TypeScript 4.9+，函数重载是语义更清晰、无需断言的首选：

function convertToV2(shape: CircleV1): CircleV2;
function convertToV2(shape: SquareV1): SquareV2;
function convertToV2(shape: ShapeV1): ShapeV2 {
  switch (shape.type) {
    case "circle":
      return { ...shape, sides: 1 } satisfies CircleV2; // ✅ satisfies 捕获构造错误
    case "square":
      return { ...shape, sides: 4 } satisfies SquareV2;
  }
}

satisfies 关键字能静态校验对象字面量是否恰好满足目标类型（而非仅是子类型），例如误写 type: "square" 在 circle 分支中会立即报错，大幅提升重构安全性。

⚠️ 注意事项

• 避免过度依赖 any 或 unknown：它们会破坏类型链路，使推导失效；
• 泛型约束需严谨：T extends ShapeV1 确保输入始终是合法判别联合成员；
• 辅助函数必须覆盖所有 type 可能值：否则 switch 缺少 default 或遗漏 case 将导致运行时错误；
• satisfies 是 TS 4.9+ 特性：旧版本可用 as CircleV2 替代，但失去构造校验。

通过上述任一方案，你都能实现「输入即契约，输出即承诺」的强类型迁移函数，在保持代码简洁的同时，获得 IDE 智能提示、编译期保障与无缝类型推导。