TypeScript 类型推断配合 JSDoc 可在纯 JS 异步代码中实现类型安全与文档同步：启用 tsconfig.json 的 allowJs、checkJs 等选项，用 JSDoc 标注 Promise 返回值、参数及 error 类型，并结合 import 语句绑定接口定义，使 IDE 补全、tsc 校验与 apidoc 文档生成三者联动。
直接用 TypeScript 的类型推断能力配合 JSDoc，就能在纯 JavaScript 异步代码中实现类型安全校验和文档自动同步——不需要改后缀、不重构、不中断现有构建流程。
配置 TypeScript 检查异步 JS 文件
关键不是写 .ts，而是让 tsc “读懂”你的 .js。只需两步：
- 在 tsconfig.json 中启用：
"allowJs": true和"checkJs": true - 建议同时开启
"strictNullChecks": true和"noImplicitAny": true，避免 Promise 返回值被默认当作any - 无需安装额外插件，VS Code 和命令行
tsc --noEmit都能立刻响应
用 JSDoc 精确标注异步行为
异步逻辑的类型最容易出错的地方是返回值、参数解构、错误处理路径。JSDoc 要写得像 TS 接口一样严谨：
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
/** @param {string} id */→ 明确参数类型，防止fetchUser(id)传入null或对象 -
/** @returns {Promise<User>} */→ 让 IDE 知道await fetchUser()解构出的是User，不是any -
/** @type {import('./types').ApiResponse<ProductList>} */→ 对const res = await api.get(...)做强类型绑定，res.data.map才有补全 - 对
try/catch中的error，可用/** @type {Error & { code?: string }} */补充运行时可能字段
让 API 文档与异步类型自动对齐
apidoc 支持从 JSDoc 提取接口描述，但只有加上 TypeScript 类型才能保证字段不漏、必填不错：
- 在路由函数上方写标准 apidoc 注释（如
@api {GET} /users），再叠加@returns {Promise<User[]>} - 配置
apidoc.json启用 TypeScript 解析："typescript": { "enabled": true, "tsconfig": "./tsconfig.json" } - 生成的 HTML 文档里，
Response Body字段会自动映射到User类型定义中的属性，包括可选标记[optional] - 如果后端响应加了新字段但没更新 JSDoc 类型，tsc 会报错，文档生成也会失败——形成硬性约束
覆盖动态异步结构：类型定义 + JSDoc 导入
API 响应、WebSocket 消息、localStorage 解析结果等，往往无法靠推断获得完整类型。这时要组合使用：
- 在
types/api.d.ts中定义：export interface OrderResponse { id: string; items: CartItem[]; } - 在 JS 文件中写：
/** @type {import('./types/api').OrderResponse} */ const order = JSON.parse(str); - VS Code 立刻识别
order.items[0].price是 number，访问.discountRate会标黄提示不存在 - 这种写法也兼容 apidoc，它会把
OrderResponse的字段结构一并渲染进文档
