这样 VSCode 会对 JS 文件里的 JSDoc 进行类型检查。

. JSDoc在实际开发中的使用场景

对象 / 数组 类型提示

普通对象

// @ts-check/** * @typedef {Object} User * @property {string} name * @property {number} age * @property {boolean} isAdmin *//** @type {User} */const user = { name: 'Tom',age: 18,isAdmin: false }user.name // ✅ string 提示user.age // ✅ number 提示user.isAdmin // ✅ boolean 提示
// 错误示例
user.xxx // ❌ 报错。没有这个属性
user.age = '18' // ❌ 类型错误，应为 number

数组

/** @type {User} */const users = users.age // ✅ number 提示
// 错误示例
users.push // ❌ 类型错误，应为 User 对象
users.xxx // ❌ 属性不存在

. JSDoc函数参数与返回值

/** * @param {number} x * @param {number} y * @returns {number} */function add {return x + y;}add // ✅ number 类型add // ❌ 参数类型错误
// 错误示例
const result = add // ❌ 返回值类型错误，影响后续操作
result.toFixed // ✅ 确保 result 是 number 才有 toFixed 方法

. JSDoc函数回调

/** * @callback Comparator * @param {string} a * @param {string} b * @returns {number} *//** * @param {string} arr * @param {Comparator} compare */function sortStrings {
return arr.sort;}
sortStrings => a.length - b.length)
// ✅ a 和 b 自动推导为 string，且有类型检查
// 错误示例
sortStrings => a + b) // ❌ 返回值应为 number
sortStrings => num + b) // ❌ num 不是 string 类型
sortStrings => a - b) // ❌ 数组元素不是 string 类型

. JSDoc泛型

/** * @template T * @param {T} arr * @returns {T} */function first {
return arr;
说起来，}

first // ✅ 返回 number 类型 first // ✅ 返回 string 类型 first.id // ✅ id 为 number 类型

// 错误示例 first.xxx // ❌ 空数组调用 first 可能返回 undefined。应该处理边界情况或添加判断后再使用返回值属性。const value = first value.toFixed // ❌ value 是 string 类型，没有 toFixed 方法。first // ❌ 参数不是数组时会报错或返回错误结果。first // 同上，应该校验输入参数。

利用泛型可以实现非常灵活的类型推导。同时配合 TypeScript，可以获得强大的代码补全和校验能力。即使在纯 JavaScript 项目中。也可以这样得到接近 TypeScript 的开发体验，大大提高代码的可维护性与健壮性。不过，结合编辑器的智能提示。可以减少很多不必要的运行时错误，提高开发效率。

当然要想最大化发挥 JSDoc 的优势，还需要一些常用方法和工具链的支持。比如合理配置 tsconfig.json/jsconfig.json，利用编辑器插件提高代码补全和校验，甚至可以自定义一些代码片段或工具函数，进一步简化开发流程，提高团队协作效率。

在现代前端开发中，利用 JSDoc + TypeScript 推导的方式。不光可以帮助我们写出更安全、更高效的 JavaScript 代码，还能让我们的项目保持更好的灵活性与可 性，是值得尝试和推广的常用方法之一。

最终如果你还在犹豫是否要在项目中使用 JSDoc，不妨从简单的场景入手。比如先给关键函数添加类型注释，或者在公共组件/工具库中使用 JSDoc 来提供更好的 API 文档和类型约束。相信因为实践的深入，你会逐渐体会到它的价值所在！

希望这篇文章能帮助你更好地理解和应用 JSDoc，为你的前端开发带来更多便利！怎么说呢，😊

再比如说我们在封装一些通用逻辑的时候，可以通过jsdoc+ts type 来实现功能比较强的自动补全还有校验能力： 比如下面这个例子： /** * 从任意对象结构中提取指定 key 并返回新对象 * 支持通过泛型指定输入输出结构以获得完整类型推导和补全

• 再看使用场景，
• • 从复杂数据结构中提取需要的字段，减少冗余数据传输
• • 在状态管理或数据转换过程中标准化输出格式

• 示例的观点是，

• pick => { name: 'Tom'。info: { age: 18 } }

• pickDeep => 按嵌套方法提取深层字段

• TODO的观点是，

• • 支持更多方法表达式
• • 增加性能调整 *
• 至于参考，

• lodash.get / ramda.path - 类似工具库的实现思路可以参考

• 主要难点 & 踩坑点：

• • 如何处理嵌套方法的类型推导？
• • 如何避免误用？

* * 相关 Issue： * https://github.com/xxx/yyy/issues/123

* @category Object Utils @subcategory Data Transform

* @example js import pick from './pick'

const user = { name这方面，'John',address: { 再看city，'New York',zip: '10001' },contacts: { 从email来看，''。phone: '+11234567890' } }

// 简单提取顶层字段 const result1 = pick console.log // 输出：{ name: 'John' }

// 按方法提取深层字段 const result2 = pick console.log // 输出：{ city: 'New York',email: '' }

// 按方法提取并保留结构 const result3 = pickDeep console.log // 输出： // { // address: { // city: 'New York' // },// contacts: { // email: '' // } // }

// 错误用法演示 pick // 🚨 应为 string pick // ⚠️ 方法不存在的处理方式待调整

*/