如何用JSDoc注释Express中间件？

Question

我正在尝试记录Express中间件,但WebStorm中的内置验证工具告诉我在以下JSDoc块中错误地分配了类型:

/**
 * My middleware.
 *
 * @param {Object} req
 * @param {Object} res
 * @param {Function} next
 * @return {Object}
 */
exports.show = function(req, res, next) {
    ...
};

在Express消息来源中,我没有找到任何@typedef帮助我.另外,我想避免像这样的事情@param {*}.

使用JSDoc记录Express中间件的正确方法是什么？谢谢你的帮助.

Answer 1

您可以使用以下方法记录您的中间件

const express = require("express");

/**
 * @param {express.Request} req
 * @param {express.Response} res
 * @param {express.NextFunction} next
 */
function (req, res, next) {}

当您有向 req 添加属性的中间件时，您还可以添加它们

const express = require("express");

/**
 * @param {express.Request & {specialParam1 : string, specialParam2 : any}} req
 * @param {express.Response} res
 * @param {express.NextFunction} next
 */
function (req, res, next) {}

或者更好的事件，为“req”上添加的每个新元素源创建一个typedef，并使用“&”创建一个将它们组合在一起的类型。

Answer 2

[2021-03-02 更新] 原始答案是 100% JSDOC + 0% typescript，但我找到了 20% JSDOC + 80% typescript（纯定义）解决方案。在typescript github中，提到了这个方法。请参阅帖子的最后一段。

我结合其他答案并修改一些代码，
它可以包括事件自定义请求主体上定义的所有方法/属性express.Request。
它不仅可以使用request.body，还可以支持req.query。
因为express.Request支持泛型，所以我们可以在 JSDoc 中使用它。

首先，记得@types/express安装npm install --save-dev @types/express。

其次，像下面的代码一样设置。

// @ts-check
/**
 * @typedef {object} showRequestBody
 * @property {string} name this is name in request body
 * @property {number} age this is age in request body
 * 
 * @typedef {object} showRequestQuery
 * @property {string} name this is name in query
 * @property {number} age this is age in query
 * 
 * @param {import('express').Request<{}, {}, showRequestBody, showRequestQuery>} req
 * @param {import('express').Response} res 
 * @param {import('express').NextFunction} next 
 */
exports.show = function(req, res, next) {
};

注：我在vscode中使用它。
我在这里留下答案，希望这能帮助其他也有这个问题的人。

express.Request例如，在 上定义的其他方法/属性req.headers

req.body暗示

req.query暗示

20% JSDOC + 80% 打字稿

以下示例不需要tsconfig.json或安装额外的tsc.
但是，您无法使用 jsdoc 生成文档。

具有导入+导出定义

如果你想通过导入某些模块来扩展接口，你需要在定义中使用export。然后将其导入JSDOC。

没有导入+导出定义

如果你不想在JSDOC中导入自定义的定义，你可以只定义接口，而不需要导入和导出。然后就可以直接在JSDOC中使用它了。

扩展express模块

还有另一种构建自定义接口的方法，只需使用声明模块来扩展接口。您甚至可以定义自定义方法。

Answer 3

您不仅可以在 JsDoc 中获取参数类型和描述，还可以获取它们的预期成员。

/**
 * 
 * @module myMiddleware
 * @function
 * @param req {Object} The request.
 * @param res {Object} The response.
 * @param req.params.foo {String} The foo param.
 * @param req.query.bar {String} The bar query.
 * @param req.body {Object} The JSON payload.
 * @param {Function} next
 * @return {undefined}
 */
function foo(req, res, next){
}

Answer 4

使用DefinitelyTyped

1. 安装快递类型 npm install --save-dev @types/express
2. 通常使用e.Response@param {e.Response} res

更多类型

• 在文件中 /node_modules/@types/express/index.d.ts
• 对于Response，它是e.Response，因为：

... declare namespace e { ... export interface Response extends core.Response { } ...

网络风暴

通过设置>语言和框架> Javascript>库> @ types / express安装类型

Answer 5

首先,我们同意中间件是功能; 通常不需要特殊类型声明.除此之外,中间件往往是高度解耦 - 模块化 - 这意味着@module标签通常是适用的(当你运行jsdoc时这会产生很好的结果).

/**
 * Description of my middleware.
 * @module myMiddleware
 * @function
 * @param {Object} req - Express request object
 * @param {Object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @return {undefined}
 */

返回标记是可选的,具体取决于您的样式指南,因为中间件不返回值.最后,与Nick和mmm声称的相反,next参数是一个函数.

http://expressjs.com/en/guide/using-middleware.html

中间件函数是可以访问请求对象(req),响应对象(res)以及应用程序请求 - 响应周期中的下一个中间件函数的函数.下一个中间件函数通常由名为next的变量表示.

next不是一种花哨的快速内部混合物; Express将每个中间件功能传递给堆栈中的请求,响应和下一个中间件功能,如下所示:

mw1 = function(req, res, next){}.bind(undefined, req, res, mw2)
mw2 = function(req, res, next){}.bind(undefined, req, res, mw3)

next范围内的值mw1是mw2.

Answer 6

req、res和next都是对象，中间件通常不会返回，因此可以使用以下内容。

/**
 * My Middleware
 * @name MyMiddleWare
 * @function
 * @param {Object} req
 * @param {Object} res
 * @param {Object} next
 */