TypeScript函数选项参数的合理类型定义模式探究

核心模式：泛型约束+默认值合并+自动类型推断 #

针对你提出的三个目标，最合理的实现方式是通过泛型约束用户传入的选项类型，结合对象展开合并默认值，同时让TypeScript自动推断最终的选项类型。这种模式既能保证类型安全，又能精确反映合并默认值后的选项结构，进而作用于返回值类型。

基础实现（严格限制选项为默认子集） #

先定义默认选项的类型和实际值：

// 基础默认选项类型
type DefaultOptions = {
  enableLog: boolean;
  maxRetries: number;
  timeout: number;
};

// 实际默认值
const defaultOptions: DefaultOptions = {
  enableLog: false,
  maxRetries: 3,
  timeout: 5000,
};

然后实现核心函数：

// 泛型O约束为DefaultOptions的部分类型，自动推断用户传入的选项
function createService<O extends Partial<DefaultOptions>>(
  options?: O
): { opts: DefaultOptions & O } {
  // 用户传入选项覆盖默认值，生成最终配置
  const mergedOpts = { ...defaultOptions, ...options } as DefaultOptions & O;
  return { opts: mergedOpts };
}

效果验证 #

• 不传参数时，自动应用全部默认值，返回值的opts类型为完整的DefaultOptions：

  const service1 = createService();
  // service1.opts.enableLog 类型为字面量false，maxRetries为3，timeout为5000
  

• 传入部分选项时，自动合并默认值，返回值的opts类型为默认类型与传入选项的交集：

  const service2 = createService({ enableLog: true, timeout: 10000 });
  // service2.opts.enableLog 类型为字面量true，timeout为10000，maxRetries为3
  // 完整类型：DefaultOptions & { enableLog: true; timeout: 10000 }
  

扩展实现（允许自定义额外选项） #

如果需要支持默认选项之外的自定义参数，可以调整泛型约束为任意对象类型：

type DefaultOptions = {
  enableLog: boolean;
  maxRetries: number;
};

const defaultOptions: DefaultOptions = {
  enableLog: false,
  maxRetries: 3,
};

// 泛型O允许任意对象类型，支持扩展自定义选项
function createService<O extends Record<string, unknown>>(
  options?: O
): { opts: DefaultOptions & O } {
  const mergedOpts = { ...defaultOptions, ...options } as DefaultOptions & O;
  return { opts: mergedOpts };
}

// 使用示例
const service = createService({ timeout: 5000, customTag: "api-service" });
// service.opts 的类型：DefaultOptions & { timeout: number; customTag: string }

模式优势 #

• 自动类型推断：无需手动指定泛型，TypeScript会根据用户传入的options自动推断泛型O的类型
• 默认值自动应用：通过对象展开语法{...defaultOptions, ...options}，确保未传入的选项自动使用默认值
• 精确类型反馈：合并后的类型DefaultOptions & O精确反映最终的选项结构，包括字面量类型，能直接作用于返回值的类型定义，满足返回值依赖选项结构的需求
• 类型安全：泛型约束确保传入的选项要么是默认类型的子集，要么是合法的自定义对象，避免非法参数

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