TypeScript .d.ts文件中定义闭包函数返回类型的最佳实践

现有手写版本的可优化点 #

你当前手写的声明可以正常工作，但存在几个明显问题：

• 闭包内部的setupHandler、setProcess是函数作用域内的私有方法，外部无法直接访问，不需要在顶级作用域单独声明，会污染全局类型空间
• 入参、返回值大量使用any，丢失类型信息，无法达到理想的智能提示效果
• 第二版声明里所有方法都标注为() => void，完全不符合实际逻辑，提示信息完全无效
• 导出方式需要和JS的实际导出逻辑匹配：如果JS采用CommonJS的module.exports = handler写法，需要用export = handler，不要用ESModule的export default，否则会出现导入类型不匹配的问题。

针对示例Demo的最优声明写法 #

不需要单独声明闭包内部函数，直接在返回值接口中定义结构即可，同时补全参数类型避免any：

// 定义入参config结构，按需扩展字段
interface ProcessConfig {
  value?: number;
  // 存在不确定扩展字段时可以加索引签名
  [key: string]: any;
}

// 定义handler返回值结构
interface HandlerReturn {
  setup: (config: ProcessConfig) => ProcessConfig;
  process: {
    set: (cnf: ProcessConfig) => boolean;
    options: {
      // 固定常量可以直接写字面量类型，提示更精准
      value: 10;
    }
  }
}

declare function handler(): HandlerReturn;

export = handler;

实际项目场景的优化方案 #

针对你提到的进程管理模块，可以按结构分层定义类型，兼顾可读性和提示精度：

// 先定义核心配置类型，对应项目内config模块的实际结构
interface ProcessConfig {
  cwd?: string;
  env?: NodeJS.ProcessEnv;
  timeout?: number;
  // 按实际配置字段补全即可
  [key: string]: any;
}

// 单独定义process子模块的类型结构，拆分后更易维护
interface ProcessSubModule {
  set: (config: ProcessConfig) => boolean;
  get: () => ProcessConfig;
  registerHandlers: (handlers: Record<string, Function>) => void;
  exec: (command: string, options?: ProcessConfig) => Promise<{stdout: string; stderr: string}>;
  execFile: (file: string, args?: string[], options?: ProcessConfig) => Promise<{stdout: string; stderr: string}>;
  fork: (modulePath: string, args?: string[], options?: ProcessConfig) => NodeJS.ChildProcess;
  spawn: (command: string, args?: string[], options?: ProcessConfig) => NodeJS.ChildProcess;
  executeProcess: (config: ProcessConfig) => Promise<number>;
  executeAction: (action: string, config?: ProcessConfig) => Promise<any>;
  kill: (pid: number, signal?: NodeJS.Signals) => boolean;
  options: {
    value: number;
  }
}

interface HandlerReturn {
  setup: (config: Partial<ProcessConfig>) => ProcessConfig;
  process: ProcessSubModule;
}

/**
 * 进程执行与管理处理函数
 * @returns 进程模块方法集合
 */
declare function handler(): HandlerReturn;

export = handler;

提效技巧 #

如果不想完全手写声明，可以在JS源码中补充标准JSDoc类型标注，执行你之前用的tsc生成声明命令时，TS会自动读取JSDoc信息推导类型，减少手动维护量。比如给函数参数补@param、给返回值补@returns标注，就不会生成any类型的声明。

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