使用 JSDoc 标注 Promise 类型可提升 JavaScript 代码的可读性和维护性。1. 用 @returns {Promise<T>} 明确函数返回值类型，如 {Promise<{id: number, name: string}>}，使编辑器能推断异步结果结构；2. 用 @param {Promise<T>} 注解参数类型，如接收字符串数组 Promise 的函数，明确要求传入 resolve 为 string[] 的 Promise；3. 支持多种泛型形式，包括 Promise<string>、Promise<number[]>、Promise<void> 和 Promise<?boolean> 等；4. 在启用 checkJs 或使用支持 JSDoc 的 IDE（如 VSCode）时，可实现静态类型检查与智能提示，有效捕获类型错误。正确使用这些注解有助于团队协作和复杂异步逻辑维护。
在 JavaScript 中使用注解（如 JSDoc）标注 Promise 对象，可以帮助编辑器和团队成员更好地理解函数返回值的类型，尤其是在异步操作中。虽然 JS 是动态类型语言，但通过 JSDoc 可以实现类似静态类型的提示效果。
1. 使用 @returns 标注 Promise 返回类型
当你有一个返回 Promise 的函数时，可以用 @returns {Promise<T>} 来说明它 resolve 的值类型，其中 T 是实际的数据类型。
/**
* 获取用户信息
* @returns {Promise<{id: number, name: string}>} 用户对象的 Promise
*/
function fetchUser() {
return fetch('/api/user').then(res => res.json());
}
这样 VSCode 或 WebStorm 就能识别 fetchUser().then(user => user.name) 中 user 的结构，提供自动补全和类型检查。
2. 标注 Promise 参数类型
如果函数接收一个 Promise 类型的参数，可以使用 @param {Promise<T>} 来标注。
/**
* 处理数据 Promise
* @param {Promise<string[]>} dataPromise - 字符串数组的 Promise
* @returns {Promise<string>} 拼接后的字符串
*/
async function processList(dataPromise) {
const list = await dataPromise;
return list.join(', ');
}
这种写法让调用者清楚知道传入的参数应是一个 resolve 为字符串数组的 Promise。
3. 常见泛型类型示例
Promise 内部类型可以是任意合法的 JSDoc 类型：
- {Promise<string>} —— resolve 一个字符串
- {Promise<number[]>} —— resolve 一个数字数组
- {Promise<void>} —— 不返回有意义的值（类似 async 函数默认）
- {Promise<?boolean>} —— 可能 resolve 为 boolean 或 null
4. 配合 TypeScript 或 IDE 使用更佳
即使项目是纯 JS，启用 checkJs（在 tsconfig.json 中）或使用支持 JSDoc 的编辑器，可以让这些注解真正起作用，捕获潜在类型错误。
基本上就这些。正确标注 Promise 类型，能显著提升代码可读性和维护性，尤其在复杂异步逻辑中。不复杂但容易忽略。
