无需重写旧JS项目，通过TS类型推断+JSDoc注解即可增强async/Promise代码的可读性、可查性和防御性：精准标注Promise返回值、统一约束async函数签名、显式定义动态结构，并启用checkJs与文档生成实现类型校验和自动化文档。
直接在旧 JS 项目中加 TypeScript 编译会卡在大量 async 函数、Promise 链和动态响应结构上。不用重写，靠 TS 的类型推断能力 + JSDoc 注解就能让异步逻辑可读、可查、可防御。
为 Promise 返回值精准标注类型
旧代码里常见 fetch().then(res => res.json()) 或 await api.get('/user')，但返回结构模糊。不能只写 @type {Promise}，要具体到数据形态：
- 用
import()引入定义好的响应类型，比如后端接口已声明interface UserResponse { id: string; name: string }在types/api.d.ts中 - 在调用处加注解：
/** @type {Promise} */ const user = await api.get('/user'); - 编辑器立刻识别
user.name可访问、user.email报错（若未定义），无需运行就暴露字段缺失
给 async 函数参数与返回统一约束
旧的异步工具函数往往没签名，比如一个封装了重试逻辑的 safeFetch：
- 在函数声明前加完整
@type，覆盖参数、返回、甚至this上下文：
/** @type {(url: string, opts?: RequestInit) => Promise} */ function safeFetch(url, opts) { ... } - 如果返回需进一步解析，可拆成两层注解：
先标函数本身返回Promise，再在调用处单独标/** @type {Promise} */ const list = safeFetch('/orders').then(r => r.json()); - 这样既不改动函数体，又让所有调用点获得结构提示和错误拦截
处理运行时动态结构（如表单提交、API 聚合）
很多旧逻辑依赖 new FormData(form) 或 Object.assign({}, ...apis)，结构无法静态预判。这时类型定义要前置、显式、可复用：
- 在
types/form.d.ts中定义：export interface LoginForm { email: string; password: string; remember?: boolean; } - 在 JS 文件中使用内联引用：
/** @type {import('./types/form').LoginForm} */const data = Object.fromEntries(new FormData(form)); - 若字段来自多个来源，用交叉类型组合：
/** @type {import('./types/api').UserProfile & import('./types/form').LoginMeta} */
启用检查并生成文档一步到位
光写注解没用，必须激活 TS 的 JS 支持和文档提取链：
- 确保
tsconfig.json含："allowJs": true,"checkJs": true,"maxNodeModuleJsDepth": 2（用于解析 node_modules 里的 JSDoc 类型） - 运行
npx tsc --noEmit即可校验全部 JS 文件中的类型一致性，失败即中断 CI - 用
jsdoc -c jsdoc.json扫描带@param/@returns的异步函数，自动生成含 Promise 类型说明的 HTML 文档页
