Node.js Express中如何为Response自定义方法编写JSDoc并消除类型警告？

问题描述 #

我正在开发一个JavaScript语言的Express.js项目，希望通过JSDoc注释为Express Response对象添加自定义的error和success函数，统一处理响应。尝试用@typedef定义了CustomResponse，但仍收到警告：Property 'error' may not exist on type 'Response<any, Record<string, any>, number>'。相关代码如下：

@typedef {object} CustomResponse
@property {Function} error - A function to handle error responses.

/**
 * *Route for handling 404 Not Found errors.
 * *This middleware will catch any request that does not match any other route handlers.
 *
 * @param {import('express').Request} req - The Express request object.
 * @param {import('express').Response} res - The Express response object.
 * @param {import('express').NextFunction} next - The next function to pass control to the next middleware.
 *
 * @date 07 September 2023
 */
app.all('*', (req, res) => {
    return res.error(
        HTTPStatus.NOT_FOUND,
        'The requested resource could not be found but may be available in the future'
    );
});

解决方案 #

1. 用JSDoc扩展Express Response类型 #

不要单独定义独立的CustomResponse，而是通过类型交叉（&）将自定义方法合并到Express原生的Response类型上：

/**
 * @typedef {import('express').Response} ExpressResponse
 * @typedef {ExpressResponse & {
 *   error: (statusCode: number, message: string) => void;
 *   success: (statusCode: number, data?: any, message?: string) => void;
 * }} CustomResponse
 */

然后在路由的JSDoc参数中使用这个扩展后的CustomResponse类型：

/**
 * 处理404 Not Found错误的路由
 * 该中间件会捕获所有未匹配到其他路由的请求
 *
 * @param {import('express').Request} req - Express请求对象
 * @param {CustomResponse} res - 扩展后的Express响应对象
 * @param {import('express').NextFunction} next - 传递控制权给下一个中间件的函数
 *
 * @date 2023年9月7日
 */
app.all('*', (req, res) => {
    return res.error(
        HTTPStatus.NOT_FOUND,
        '请求的资源未找到，但未来可能可用'
    );
});

2. 使用类型声明文件扩展（适合VS Code/TypeScript检查） #

如果你的项目启用了TypeScript的JS检查（通过javascript.implicitProjectConfig.checkJs: true），可以创建一个类型声明文件（比如types/express.d.ts）来全局扩展Express的Response接口：

// types/express.d.ts
declare namespace Express {
  interface Response {
    error(statusCode: number, message: string): void;
    success(statusCode: number, data?: any, message?: string): void;
  }
}

然后在你的JS文件顶部添加引用：

/// <reference path="./types/express.d.ts" />

这样编辑器就能自动识别Response对象上的自定义方法，不再抛出警告。

3. 确保编辑器识别JSDoc #

在VS Code中，确保开启了JavaScript的类型检查：

• 打开设置（Ctrl+,）
• 搜索javascript.implicitProjectConfig.checkJs并勾选启用

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