如何在JSDoc中指定字符串参数的匹配正则？无需第三方库是否可行？

结论 #

原生JSDoc标准本身不支持你示例中直接将正则表达式嵌入类型声明的写法，{string/^[a-z0-9]+$/i}这种语法会被识别为无效类型。

不引入外部库的实现方案 #

你可以通过以下两种方式在无额外依赖的情况下满足需求：

• 文档标注说明：直接在参数描述里明确正则要求，所有查看JSDoc的开发者都能清晰看到约束：

/**
 * 处理字母数字字符串
 * @param {string} str 必须匹配正则 `^[a-z0-9]+$/i` 的字母数字字符串
 */
function doSomething(str) {
  // 函数逻辑
}

• 文档+运行时校验结合：在函数内部补充正则校验逻辑，即使传入不符合要求的参数也能及时拦截报错，搭配JSDoc说明效果更好：

/**
 * 处理字母数字字符串
 * @param {string} str 必须匹配正则 `^[a-z0-9]+$/i` 的字母数字字符串
 */
function doSomething(str) {
  const alphaNumReg = /^[a-z0-9]+$/i
  if (!alphaNumReg.test(str)) {
    throw new TypeError(`参数str必须是字母数字字符串，当前值：${str}`)
  }
  // 函数逻辑
}

扩展说明 #

如果你使用支持JSDoc的TypeScript做静态校验，部分简单的格式要求可以通过模板字面量类型实现静态校验，比如版本号格式可以写为@param {v${number}.${number}.${number}} version，但复杂的正则规则依然无法直接通过类型实现静态校验。

内容的提问来源于stack exchange，提问作者AncientSwordRage