javascript - JSDoc - 带有部分创建的类型定义

Question

我们使用 Webstorm 和 JSDoc 来提供一些不错的建议功能，并在需要时提供类型文档。

例如，这是 User 的定义，它在应用程序中多次使用。

/**
     * Basic user object
     * @typedef {Object} User
     * @property {!Number} id - Unique identitifaction
     * @property {!String} email - Email and username in once
     * @property {!Boolean} enabled - True, if user can access the system
     * @property {!Boolean} confirmed - True, if validation (i.e. through email) was successfull
     *
     * @property {?String} name - Name of user
     */

然后我们可以在服务方法中使用他来通过用户的一些细节进行选择

/**
 * return Detail of user
 * @param {User} params
 * @param {Options=} options
 * @returns Promise.<User>
 */
exports.userDetail = (params, options = {}) => {
    return userRepository.userDetail(params, options);
};

到目前为止，它的效果非常好，当我在 exports.userDetail 方法中使用 params 时，它会自动建议我们可以使用的字段(如果我们愿意)。

问题是“在树顶”。例如，详细的标准 CRUD 操作是使用此方法并仅通过 id 选择

/**
 * @param {Number} req.userId
 */
exports.detail = (req, res, next) => {
    return userService.userDetail({id: req.userId}).then(user => {
        res.out = user;
        return next();
    }).catch(next);
};

但是，在这部分{id: req.userId} webstorm 调用错误:“参数类型...无法分配给参数类型 User”

唯一的解决方案是命名所有属性，否则它会这样说。对于其他情况，此警告确实很有帮助 - 它会发现，如果您错误地将 Number 放入字符串中或将 Token 放入 User 中等。但是，将真正的错误与此错误混合在一起会使其可靠性降低。

有人对 JSDoc 或 Webstorm 有一些一般性的建议吗？我没有找到一种方法来表达“即使没有所有字段，该参数也是用户的，并非所有字段都是必填的”。

另一方面，我想在整个应用程序中共享一个模型 - 我可以在每个函数中编写完整的定义，该函数可以正常工作

/**
 * Register standard user
 * @param {String} _params.email Unique email for registration, used also instead of username
 * @param {String} _params.password Password for your account
 * @param {Options=} options
 */

但是当我们在很多方法中使用 User 时，每次更改都意味着在整个应用程序中更新它需要大量工作(当它变得足够大时几乎不可能)

Answer 1

您可以尝试将属性定义为可选 - 例如

/**
     * Basic user object
     * @typedef {Object} User
     * @property {!Number} id - Unique identitifaction
     * @property {!String} [email] - Email and username in once
     * @property {!Boolean} [enabled] - True, if user can access the system
     * @property {!Boolean} [confirmed] - True, if validation (i.e. through email) was successfull
     *
     * @property {?String} name - Name of user
     */