如何用JSDoc注释Express中间件?

时间:2014-12-03 08:27:05

标签: javascript express webstorm jsdoc

我试图记录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中间件的正确方法是什么?谢谢你的帮助。

7 个答案:

答案 0 :(得分:6)

First, we agree that middleware are functions; no special type declaration will generally be warranted. Beyond that, middleware tend to be highly decoupled—modular—which means the @module tag is usually applicable (and this has nice consequences when you run 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}
 */

The return tag is optional depending on your style guide, since middleware don't return a value. Finally, contrary to what Nick and mmm claim, the next parameter is a function.

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

Middleware functions are functions that have access to the request object (req), the response object (res), and the next middleware function in the application’s request-response cycle. The next middleware function is commonly denoted by a variable named next.

next isn't a fancy Express-internal concoction; Express passes each middleware function the request, the response, and the next middleware function in the stack, like this:

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

The value of next within the scope of mw1 is mw2.

答案 1 :(得分:4)

使用DefinitelyTyped

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

更多类型

  • 在文件/node_modules/@types/express/index.d.ts
  • 对于响应,它是 e.Response ,因为:

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

WebStorm

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

安装类型

答案 2 :(得分:1)

您不仅可以使用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){
}

答案 3 :(得分:0)

reqresnext都是对象,中间件通常不返回,因此可以使用以下内容。

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

答案 4 :(得分:0)

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

答案 5 :(得分:0)

您可以使用以下文档记录中间件

static void Main(string[] args)
        {
            Console.Write("Enter age");
            string str = Console.ReadLine();
            int MyAge = Convert.ToInt32(str);
            int money = 15000;
            {
                do
                {
                    {
                        if (money > 20000 || MyAge < 60)
                        {
                            Console.Write("You are saving little");
                            money = money + 500;
                        }
                        else
                        {
                            Console.Write("You are saving a lot");
                            money = money + 1000;
                        }
                        MyAge++;
                    }
                }
                while (money < 40000 && MyAge < 65);
            }

            Console.Write("You are retired by the age of " + MyAge + " and you saved " + money + " dollars.");
    }

当您具有将属性添加到req的中间件时,也可以使用

添加它们
const express = require("express");

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

或者更好的方法是,为添加到“ req”上的新元素的每个源创建一个typedef,并使用“&”创建一个将它们全部结合在一起的类型。

答案 6 :(得分:0)

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

首先,请记住将@types/expressnpm 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提示