在JavaScript项目开发中，函数参数的约束一直是开发者关注的问题，尤其是必填参数的标注，能让调用方更清晰地知道函数需要哪些参数，也能配合工具做类型检查和提示。通过JS注解标注必填参数是目前主流的解决方案。
常用的JS注解规范
目前最通用的JS注解规范是JSDoc，它是一套用于JavaScript代码的文档生成规范，支持参数类型、必填性、默认值等多种标注方式，大部分IDE都能识别JSDoc注解并给出对应的代码提示。
JSDoc基础参数标注语法
JSDoc使用@param标签来标注函数参数，基本语法为@param {类型} 参数名 参数描述，如果需要标注必填参数，只需要在参数名前添加!标识即可，这是JSDoc中标注必填参数的核心规则。
必填参数的具体标注方法
单个必填参数标注
如果函数只有一个必填参数，直接在@param的参数名位置加上!就可以明确标识该参数不可缺失：
/**
* 计算两个数的和
* @param {number} !a 第一个加数，必填
* @param {number} b 第二个加数，可选，默认值为0
* @returns {number} 两个数的和
*/
function add(a, b = 0) {
return a + b;
}
多个必填参数标注
当函数有多个必填参数时，每个必填参数都需要单独添加!标识，可选参数则不需要：
/**
* 创建用户账号
* @param {string} !username 用户名，必填
* @param {string} !password 密码，必填
* @param {number} !age 用户年龄，必填
* @param {string} [email] 用户邮箱，可选
* @returns {Object} 用户账号信息
*/
function createUser(username, password, age, email) {
return {
username,
password,
age,
email: email || ''
};
}
对象类型参数的必填属性标注
如果函数参数是对象类型，需要标注对象内部的必填属性，可以使用嵌套的@param语法：
/**
* 更新用户配置
* @param {Object} config 配置对象
* @param {string} config.!name 用户姓名，必填
* @param {number} config.!level 用户等级，必填
* @param {boolean} [config.isVip] 是否为VIP，可选
*/
function updateUserConfig(config) {
console.log(config.name, config.level);
}
注解的实际作用与注意事项
标注了必填参数后，IDE会在调用函数时给出参数提示，如果缺失必填参数会显示警告信息，帮助开发者提前发现问题。需要注意的是，JSDoc注解本身不会影响JavaScript代码的运行，它只是文档和提示层面的约束，如果需要运行时的参数校验，还需要额外编写校验逻辑：
/**
* 发送请求
* @param {string} !url 请求地址，必填
* @param {Object} !data 请求参数，必填
*/
function sendRequest(url, data) {
// 运行时必填参数校验
if (!url) {
throw new Error('url参数为必填项，不可缺失');
}
if (!data) {
throw new Error('data参数为必填项，不可缺失');
}
// 请求逻辑
console.log('发送请求到', url, '参数为', data);
}
常见标注误区
- 不要在可选参数前加
!，可选参数可以用[]包裹参数名，或者不加任何标识使用默认值的方式表示可选。 - 参数类型标注要准确，比如字符串类型是
string，数字是number，不要写错类型名称。 - 注解描述要清晰，说明参数的具体用途，方便其他开发者理解参数含义。
掌握JS注解标注必填参数的规范，能让团队协作时的代码沟通成本更低，也能减少因参数缺失导致的运行时错误，是提升JavaScript代码质量的有效手段。