jsdoc 标注原始类型（如 {string}）是轻量高效的方式，需用小写标准语法、搭配 @ts-check 和 jsconfig.json 启用检查，结合语义命名与运行时校验提升健壮性。

直接用 JSDoc 标注原始类型（如 {string}、{number}、{boolean}）是最轻量又见效快的方式——不改文件后缀，不加构建步骤，VS Code 开箱就能提示参数类型、悬停查看结构、编辑时校验赋值。

写对基础类型标注格式

IDE（尤其是 VS Code 的 TypeScript 语言服务）只识别标准花括号语法的类型声明。必须写全小写、无首字母大写，不能写成 {String} 或 {Number}。

• {string} ✅ 正确；{String} ❌ 不触发检查
• {string[]} ✅ 明确数组；{Array.<string>}</string> ❌ 过时写法，兼容性差
• {id: number; name: string} ✅ 结构化对象；{Object} ❌ 模糊，无提示价值

配合类型检查机制启用效果

光写 JSDoc 不够，需激活底层支持才能真正提升可读性与健壮性。

Add Typescript Best Practices

在 CLAUDE.md 中配置 TypeScript 最佳实践和代码风格规则

下载

• 在 JS 文件顶部加 // @ts-check，单文件启用 TS 类型检查
• 项目根目录配 jsconfig.json，全局开启并排除 node_modules
• 用 eslint-plugin-jsdoc 校验注释完整性，避免漏标或误标

命名 + 类型双保险增强语义

类型标注和变量命名要相互印证，让“是什么”和“干什么”一目了然。

• 布尔值优先用 isLoaded、hasPermission 命名，再配 {boolean}
• 数组统一用 userList、errorMessages 等带 List/Array 后缀的名，再标 {User[]} 或 {string[]}
• 函数参数避免 data、obj 这类泛称，改用 userInfo + {id: number; email: string}

运行时轻量校验兜底关键路径

对入口函数、API 响应解析、用户输入等关键位置，加几行 typeof 判断，既不重也不啰嗦，还能防止低级错误破坏流程。

• if (typeof id !== 'number') throw new Error('id must be number');
• if (!Array.isArray(items)) items = [];
• 封装一个 assertType(value, 'string') 工具函数，复用性强