如何使用 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

使用确定类型

1. 安装 express 类型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 2

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

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 3

首先，我们同意中间件是函数； 通常不保证特殊类型声明。 除此之外，中间件往往是高度解耦的——模块化——这意味着@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 的变量表示。

next不是花哨的 Express 内部混合物； 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 4

您不仅可以在 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 5

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

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

Answer 6

[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 模块

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

Answer 7

您唯一需要更改的是@param {Object}旁边的@param {Function} @param {Object} 。 另外， @return应该描述函数返回的内容； 例如， (Object, Array)或组合({Object|Null})