JSDOC：您向JavaScript添加类型的秘密武器（没有完整的打字稿大修）

typescript为javascript添加静态类型，有助于尽早发现错误并简化大型代码库的管理。但全面迁移到typescript有时难度很大。这时，jsdoc就派上用场了，它允许您在不进行全面重构的情况下，获得静态类型系统的大部分优势。

JSDoc的强大之处在于它不仅仅是代码注释。通过@typedef和@type，您可以在JavaScript文件中创建可复用的复杂类型定义，从而提升代码的可读性和安全性，而无需TypeScript的复杂配置。

JSDoc的适用场景：

• 小型项目: 对于小型项目，完整的TypeScript配置可能显得过于繁重。JSDoc提供了一种轻量级的添加类型和文档的方法。
• 逐步迁移: JSDoc可以作为迁移到TypeScript的桥梁。您可以先从JSDoc开始，生成声明文件，然后逐步过渡到完整的TypeScript。
• 已有JavaScript代码库: 将大型JavaScript代码库迁移到TypeScript可能非常耗时。JSDoc允许您逐步引入类型，无需一次性重写所有代码。
• 文档优先: JSDoc强调代码文档，这无论您使用哪种类型系统都是至关重要的。良好的文档始终是代码库的加分项。

使用@typedef和@type定义类型:

以下是如何使用JSDoc定义类型的示例：

立即学习“Java免费学习笔记（深入）”；

/**
 * @typedef {object} Point
 * @property {number} x - x坐标.
 * @property {number} y - y坐标.
 */

/**
 * 计算两点之间的距离.
 * @param {Point} p1 - 第一个点.
 * @param {Point} p2 - 第二个点.
 * @returns {number} 两点之间的距离.
 */
function distance(p1, p2) {
  const dx = p2.x - p1.x;
  const dy = p2.y - p1.y;
  return Math.sqrt(dx ** 2 + dy ** 2);
}

/**
 * @type {Point}
 */
const originPoint = { x: 0, y: 0 };

console.log(distance(originPoint, { x: 3, y: 4 }));

在这个例子中：

• @typedef {object} Point: 定义了一个名为Point的类型，它是一个包含x和y属性的对象，这两个属性都是数字。
• @param {Point} p1: 指定参数p1的类型为Point。
• @param {Point} p2: 指定参数p2的类型为Point。
• @type {Point}: 指定变量originPoint的类型为Point。

生成.d.ts文件:

JSDoc可以生成TypeScript声明文件（.d.ts）。TypeScript编译器（tsc）可以解析JSDoc注释并生成这些文件，这意味着您即使在编写纯JavaScript代码时，也能在IDE中进行类型检查和代码补全。

这是一个基本的tsconfig.json配置：

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "declaration": true,
    "allowJs": true,
    "emitDeclarationOnly": false, 
    "esModuleInterop": true
  },
  "include": ["./src/**/*.js"],
  "exclude": ["node_modules"]
}

运行npx tsc (或全局安装的tsc) 将在outDir目录下生成.d.ts文件。

总结:

JSDoc结合类型生成提供了一种平衡的方案。您可以获得类型安全和改进的文档，而无需承担完整的TypeScript迁移的成本。对于无法或不需要进行全面TypeScript迁移的项目，这是一种不错的选择，可以逐步引入类型并提升代码质量。 祝您编程愉快！

以上就是JSDOC：您向JavaScript添加类型的秘密武器（没有完整的打字稿大修）的详细内容，更多请关注php中文网其它相关文章！