express-x-hub配合TypeScript构建失败 无法识别isXHubValid方法

报错原因 #

express-x-hub 运行时会在 Express 的 req 请求对象上挂载 isXHubValid 校验方法，但该包没有内置官方 TypeScript 类型声明，TS 编译器默认读取的 Express Request 类型定义中不存在该属性，因此编译时抛出属性不存在的错误。

解决步骤 #

• 编写类型扩展声明文件
  在项目源码目录下（任意TS编译能扫描到的位置即可，推荐放在src/types目录统一管理自定义类型），新建express-x-hub.d.ts文件，写入以下类型扩展代码：

  import type { Request } from 'express';
  
  declare global {
    namespace Express {
      interface Request {
        /**
         * 校验请求携带的X-Hub签名是否合法
         */
        isXHubValid(): boolean;
        // 按需补充express-x-hub挂载的其他扩展属性，比如isXHub标记、解析后的bodyXHub等
        isXHub?: boolean;
      }
    }
  }
  
  export {};
  

  注意：文件末尾的空导出export {}不能省略，否则TS会将该文件识别为全局脚本而非模块，全局类型扩展不会生效。

• 校验tsconfig配置
  打开项目根目录的tsconfig.json，确认配置的文件扫描范围覆盖了刚才新建的声明文件，常规配置参考：

  {
    "compilerOptions": {
      // 其余原有配置保持不变即可
      "typeRoots": [
        "./node_modules/@types",
        "./src/types" // 如果声明文件存放在src/types目录，需要将该路径加入typeRoots，按实际存放路径调整即可
      ]
    },
    "include": ["src/**/*"]
  }
  

• 确认中间件挂载顺序
  类型配置完成后，需要保证在webhook路由注册前挂载xhub中间件，否则运行时也会出现方法不存在的错误，示例代码：

  import express from 'express';
  import xhub from 'express-x-hub';
  const app = express();
  
  // 路由前挂载xhub中间件，algorithm、secret替换为实际业务使用的配置
  app.use(xhub({ algorithm: 'sha1', secret: '替换为你的webhook签名密钥' }));
  
  // 再注册业务路由
  app.post('/webhook', function (req, res) {
    if (!req.isXHubValid()) {
      console.log('Warning - request header X-Hub-Signature not present or invalid');
      res.sendStatus(401);
      return;
    }
    res.sendStatus(200)
  })
  

补充说明 #

如果项目还未安装Express的官方类型定义，先执行安装命令：
npm install @types/express -D

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