如何在Express的JSDoc中复用函数参数定义

你可以通过JSDoc的@typedef定义一个通用的HTTP处理器类型，之后在所有处理器函数里直接复用这个类型声明，不用重复编写req和res的类型注解，具体操作如下：

1. 定义通用的HTTP处理器类型 #

首先在项目的公共文件（比如类型定义文件或入口文件顶部）定义一个可复用的类型别名：

/**
 * @typedef HttpHandlerFn
 * @type {function}
 * @param {functions.Request} req - 请求对象
 * @param {functions.Response} res - 响应对象
 */

2. 在处理器函数中复用类型 #

之后每个HTTP处理器函数只需通过@type引用这个预定义的类型即可，还可以正常添加函数自身的业务描述：

/**
 * 创建新的企业服务
 * @type {HttpHandlerFn}
 */
const createNewCompanyService = (req, res) => {
  // 编写业务逻辑
}

/**
 * 更新企业服务信息
 * @type {HttpHandlerFn}
 */
const updateNewCompanyService = (req, res) => {
  // 编写业务逻辑
}

3. 扩展类型（可选） #

如果需要支持带next参数的中间件处理器，可以扩展定义新的类型：

/**
 * @typedef HttpMiddlewareFn
 * @type {function}
 * @param {functions.Request} req - 请求对象
 * @param {functions.Response} res - 响应对象
 * @param {function} next - 中间件跳转函数
 */

然后在对应的中间件函数上引用@type {HttpMiddlewareFn}即可。

这样做不仅能减少重复代码，还能保证所有处理器的类型注解一致性，编辑器（如VS Code）也会正常提供类型提示和补全。

内容的提问来源于stack exchange，提问作者Lucas David Ferrero