本文介绍在 TypeScript 中通过泛型与条件类型实现函数返回值的精准类型推断——当 toNumberIfNeeded: true 时返回 number，否则返回 string，避免 string | number 的宽泛联合类型。
本文介绍在 typescript 中通过泛型与条件类型实现函数返回值的精准类型推断——当 `tonumberifneeded: true` 时返回 `number`，否则返回 `string`，避免 `string | number` 的宽泛联合类型。
在 TypeScript 开发中，我们常希望函数的返回类型能随输入参数的字面量值（literal value）或结构特征动态变化，而非固定为联合类型。例如，一个文本转换函数 textTransformer，其行为受 options.toNumberIfNeeded 控制：启用时解析为数字，禁用时保持字符串。若不加干预，TypeScript 默认会将返回类型推断为 string | number，丧失类型精度，影响后续类型安全调用。
要实现真正的条件返回类型，核心方案是：结合泛型约束 + 条件类型（Conditional Type）显式声明返回类型，而非依赖类型推导。
✅ 正确实现方式
首先定义选项接口（注意：推荐将可选属性设为可选，但泛型约束需兼容 undefined）：
interface Options {
uppercase?: boolean;
filterSpecialChars?: boolean;
toNumberIfNeeded?: boolean;
}接着使用泛型 T extends Options 捕获传入的 options 类型，并利用条件类型 T["toNumberIfNeeded"] extends true ? number : string 声明返回类型：
export const textTransformer = <T extends Options>(
text: string,
options?: T
): T["toNumberIfNeeded"] extends true ? number : string => {
const { uppercase, filterSpecialChars, toNumberIfNeeded } = options || {};
// 实际业务逻辑（示例）
let result: string | number = text;
if (uppercase) result = (result as string).toUpperCase();
if (filterSpecialChars) result = (result as string).replace(/[^a-zA-Z0-9]/g, '');
if (toNumberIfNeeded) result = parseInt(result as string, 10);
// 关键：类型断言确保符合声明的条件返回类型
return result as ReturnType<typeof textTransformer>;
};✅ 类型推断效果验证
const a = textTransformer("hello"); // 类型为 string
const b = textTransformer("123", { toNumberIfNeeded: true }); // 类型为 number
const c = textTransformer("456", { toNumberIfNeeded: false }); // 类型为 string
const d = textTransformer("789", { toNumberIfNeeded: Math.random() > 0.5 }); // 类型为 string | number（因运行时不确定，TS 无法窄化）
// 编译期类型安全：
a.toUpperCase(); // ✅ OK
b.toFixed(2); // ✅ OK
b.toUpperCase(); // ❌ Error: Property 'toUpperCase' does not exist on type 'number'⚠️ 注意事项与最佳实践
- 不可依赖运行时值做类型窄化：toNumberIfNeeded 若为变量（如 const flag = true），TypeScript 仍可能推断为 string | number；只有字面量布尔值（true/false）或明确的类型约束才能触发条件类型分支。
- 避免过度断言：as ReturnType<...> 是必要桥梁，但需确保逻辑中 parseInt 失败时（如 NaN）也符合语义——建议补充校验（如 isNaN() 抛错或返回 number | undefined 并调整条件类型）。
- 可选参数处理：因 options? 可为 undefined，T["toNumberIfNeeded"] 在无传参时为 boolean | undefined，此时 undefined extends true 为 false，故默认返回 string，符合预期。
-
扩展性提示：如需支持更多类型（如 Date、boolean），可升级为分布式的联合类型或使用 Record
+ 映射类型，但需权衡复杂度。
通过该模式，你不仅能精准控制返回类型，还能让 IDE 自动补全、编译器严格校验，真正发挥 TypeScript 类型系统的表达力与安全性。
