TypeScript中无需类型断言为非自有类添加新字段的方法？

场景背景 #

我拥有一个来自框架的对象实例（例如Express的Request对象），之前通过类型断言的方式扩展实例属性，但代码评审要求移除类型断言，希望找到简洁、低复杂度的替代方案（排除ES6 Proxy，因为代码量过大）。原实现如下：

interface ExtendedRequest extends Request {
  files: Record<string, Buffer>[];
}

function toExtendedRequest(req: Request, files: Record<string, Buffer>[]) {
  const extendedRequest = req as ExtendedRequest;
  extendedRequest.files = files;
  return extendedRequest;
}

解决方案 #

方案1：全局扩展Express Request类型（推荐，无断言） #

如果项目中多个地方需要使用带files属性的Request实例，直接全局扩展Express的Request接口即可，无需在函数内做任何断言。

1. 在项目中创建一个类型声明文件（例如src/types/express.d.ts）：

declare global {
  namespace Express {
    interface Request {
      files: Record<string, Buffer>[];
    }
  }
}

// 必须导出空对象以确保文件被视为模块
export {};

2. 之后直接给Request实例赋值即可，类型系统会自动识别新增的files属性：

function toExtendedRequest(req: Request, files: Record<string, Buffer>[]) {
  req.files = files;
  return req;
}

方案2：局部创建扩展对象（适合临时场景） #

如果仅需在当前函数内临时使用扩展后的对象，且允许创建原实例的浅拷贝，可以通过对象展开或Object.assign创建包含原属性和新属性的新对象，无需类型断言：

type ExtendedRequest = Request & { files: Record<string, Buffer>[] };

function toExtendedRequest(req: Request, files: Record<string, Buffer>[]): ExtendedRequest {
  return { ...req, files };
}

注意：此方法会创建原Request实例的浅拷贝，若原实例包含不可枚举属性或依赖原型链的方法，可能会丢失部分功能。仅当你只需要访问实例的基础属性时推荐使用。

方案3：类型守卫辅助（减少断言感知） #

如果必须修改原实例且不想直接使用as断言，可以通过类型守卫函数让类型系统“认可”属性已被添加：

interface ExtendedRequest extends Request {
  files: Record<string, Buffer>[];
}

// 定义类型守卫函数
function isExtendedRequest(req: Request): req is ExtendedRequest {
  return typeof (req as ExtendedRequest).files !== 'undefined';
}

function toExtendedRequest(req: Request, files: Record<string, Buffer>[]): ExtendedRequest {
  // 先通过索引签名绕开类型检查添加属性
  (req as Record<string, unknown>).files = files;
  
  // 用类型守卫让类型系统确认属性存在
  if (isExtendedRequest(req)) {
    return req;
  }
  
  // 理论上不会执行到这里，仅做兜底
  throw new Error('Failed to extend request object');
}

此方法虽然仍有一处索引签名的断言，但相比直接断言为ExtendedRequest，更符合类型安全的语义，也更容易通过代码评审。

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