近日，前端框架 Svelte 的创建者 Rich Harris 提出要将 Svelte 从 TypeScript 切换到使用 JSDoc 的 JavaScript。这种转变得到了 Svelte 团队的大力支持，他们决定在 Svelte 4 代码库中从 TypeScript 迁移到 JavaScript JSDoc。而这个决定引起了开发社区的惊讶和怀疑。

那为什么要从 TypeScript 转向 JavaScript JSDoc 呢？这是否是技术的倒退？JSDoc 又是什么？它有什么特点？如何使用？下面将详细介绍！

(资料图)

Svelte 是一个现代的 JavaScript 框架，它允许开发者以声明式的方式写组件，并在构建时将这些组件转化为高效、优化的纯 JavaScript 代码。相比于其他框架，Svelte 更加轻巧，在性能和体验方面也有着不俗的表现。使用 Svelte 可以帮助开发人员更快速地构建交互式应用程序，同时还可以减少运行时性能负担和包大小。

为什么转向JSDoc？

Svelte 团队认为，尽管类型系统非常棒，但作为一种语言，TypeScript有些“麻烦”。主要问题在于使用 TypeScript 会带来额外的工具。例如，如果在 TypeScript 中构建一个库，并在另一个项目中使用该库，就不能只修改代码库还需要重新构建代码，这增加了不必要的复杂性。

为了规避这些问题，Svelte 团队决定使用 JavaScript 和 JSDoc 注释来实现类型安全。这种方法提供了所有类型安全的好处，而没有与 TypeScript 相关的缺点。SvelteKit 代码库已经采用了这种方法，团队计划对 Svelte 4 进行同样的处理。不过，作为Svelte的用户，这不会影响在Svelte 中使用 TypeScript 的能力，从Svelte导出的函数仍将具有习以为常的所有 TypeScript 优点（类型检查、智能感知、内部文档等）。

什么是 JSDoc？

很多开发人员之所以选择 TypeScript，是因为强类型可以减少错误，并通过代码完成和弹出帮助等功能改善代码编辑器中的开发体验。而主要是 API 文档工具的 JSDoc 也可以用于类型检查。

JSDoc 是一种用于在 JavaScript 代码中编写文档和类型注释的标记语言，它使用类似于JavaDoc 的注释语法。通过在代码中添加特定的注释标记，可以生成文档，提高代码的可读性和可维护性。JSDoc不仅可以描述函数的参数和返回值类型，还可以用来描述类、对象、模块和命名空间等各种 JavaScript 实体的属性和方法。

那相较于 TypeScript，JSDoc 有什么优点呢？

与语言无关：JSDoc只是一种在类似于JavaScript的语言中编写文档和类型注释的方式，使其更加灵活。可以在各种环境中使用它，而TypeScript可能不太适合某些环境。易于集成：由于 JSDoc 只是基于注释的系统，因此不需要更改代码或工具。可以开始向现有的JavaScript代码库添加JSDoc注释，而无需太多麻烦。学习曲线较低：与TypeScript相比，JSDoc非常直接明了，学习起来更容易，TypeScript可能需要开发人员学习新的语法和类型概念。文档受益：JSDoc为编写代码文档提供了一种一致的方法。这使得其他开发人员更容易理解代码库，并有助于生成文档。渐进式采用：可以逐渐向代码库添加JSDoc，这样可以逐步将类型检查和文档引入项目，而无需完全采用TypeScript。无需构建步骤：JSDoc不像TypeScript那样需要构建步骤进行类型检查和转译。如何使用 JSDoc？

使用 JSDoc 不需要任何前置操作。只需要在 JavaScript 代码中添加 JSDoc 注释即可。JSDoc 注释以“/**”开头，以“*/”结尾，位于要描述的代码块之前。可以通过以下方式来将 JSDoc 用于类型检查。

在每个变量声明、函数声明等之前添加 JSDoc 注释，描述它们的类型和用途。例如：

/** * @type {number} */const num = 42;/** * 两数之和 * @param {number} x * @param {number} y * @returns {number} 返回值 */function add(x, y) {  return x + y;}

使用 JSDoc 注释来描述自定义类型和接口。例如：

/** * @typedef {Object} Person * @property {string} name - The person"s name. * @property {number} age - The person"s age in years. *//** * @interface Shape * @property {number} x * @property {number} y * @property {number} width * @property {number} height */

可以使用文档生成工具（如 JSDoc-to-HTML）将 JSDoc 注释自动生成为文档。例如，在使用 JSDoc 注释编写完整的库或应用后，可以使用 JSDoc-to-HTML 工具将其转换为漂亮的文档。

JSDoc 以@标记名称的形式提供了很多标记，常用的包括：

@param：用于描述函数的参数。允许指定参数名称、类型和描述信息。@returns：用于描述函数返回值的类型和描述信息。@typedef：用于定义自定义类型或对象。允许指定类型名称、属性列表和描述信息。@property：用于描述对象的属性。允许指定属性名称、类型和描述信息。@callback：用于描述回调函数的参数和返回值类型。@class：用于描述一个类。允许指定类的名称、属性、方法和描述信息。@constructor：用于描述一个构造函数。允许指定构造函数的参数、返回值和描述信息。@enum：用于定义一个枚举类型。允许指定枚举名称、属性列表和描述信息。@namespace：用于描述命名空间。允许指定命名空间的名称和描述信息。@readonly：用于指定只读属性或参数。@private：用于指定私有属性或方法。@public：用于指定公共属性或方法。@protected：用于指定受保护的属性或方法。@throws：用于描述函数可能引发的异常。允许指定异常类型和描述信息。

这些标记只是 JSDoc 提供的许多标记中的一部分。JSDoc 还提供了许多其他标记，如@augments、@example、@ignore、@link、@since等。通过使用这些标记，可以更好地记录和描述 JavaScript 代码。

需要注意，尽管可以使用 JSDoc 代替 TypeScript 进行类型检查，但它并不像 TypeScript 一样强制执行类型检查。如果在 JSDoc 注释中错误地描述了类型，或者没有提供足够的类型信息，将无法得到类型检查的保护，这可能会导致运行时错误。因此，在使用 JSDoc 进行类型检查时，需要格外小心，并尽可能详细地记录变量和参数的类型。

小结

最终 JSDoc 会取代 TypeScript 进行类型检查吗？我认为是不会的。TypeScript 非常适合应用开发，而且它正在不断改进。不过对于库开发来说，使用纯 JavaScript 和 JSDoc 注释似乎是更好的选择。

绝大多数开发人员不是在构建库，而是在构建应用。因此，TypeScript 将保持主要的类型检查方式，直到 JavaScript 实现原生类型检查为止。

选择 TypeScript 还是带有 JSDoc 的 JavaScript 取决于开发团队或开发人员的需求和偏好。对于库作者来说，JavaScript 和 JSDoc 的简单性和灵活性特别有吸引力的。对于已经具有构建中的应用，TypeScript 仍然可能是首选。