为你的 JavaScript 项目添加智能提示和类型检查

zhaochunqi 发布于2019-08-23 15:43 / 2818人阅读

摘要：前言最近在做项目代码重构，其中有一个要求是为代码添加智能提示和类型检查。调研了一段时间后，下文以编辑器作为开发工具，介绍一下如何为加上智能提示以及类型检查。

本文首发于我的博客（点此查看），欢迎关注。

前言

最近在做项目代码重构，其中有一个要求是为代码添加智能提示和类型检查。智能提示，英文为 IntelliSense，能为开发者提供代码智能补全、悬浮提示、跳转定义等功能，帮助其正确并且快速完成编码。说起来，JavaScript 作为一门动态弱类型解释型语言，变量声明后可以更改类型，并且类型在运行时才能确定，由此容易产生大量代码运行中才能发现的错误，相比 Java 等静态类型语言，开发体验上确实差了一截。更烦躁的是，智能提示就是依赖于静态类型检查的，所以在以前，指望 JavaScript 的智能提示完善度追上 Java 基本不可能。当然，时代在进步，TypeScript 已经问世许久，为 JavaScript 带来了静态类型检查以及其他诸多特性。JavaScript 的智能提示也已有了解决方案。调研了一段时间后，下文以 VSCode 编辑器作为开发工具，介绍一下如何为 JavaScript 加上智能提示以及类型检查。

基于 JSDoc

JSDoc 是目前最通用的 JavaScript API 文档生成器，根据其语法编写代码注释，可以十分方便地自动生成文档。由于 JSDoc 能提供详细的类型信息，其也被 VSCode 等编辑器接受应用于智能提示。例如，可以使用 @type 标签来赋予部分声明的 object 一个特殊类型：

/**
 * @type {{a: boolean, b: boolean, c: number}}
 */
var x = {a: true};
x.b = false;
x. // <- 由于 type 声明，"x" 将被提示含有属性 a,b 以及 c

JSDoc 最常见的使用是为函数的参数声明类型，使用 @param 来完成：

/**
 * @param {string} param1 - 这里可以用于解释参数含义
 */
function Foo(param1) {
    this.prop = param1; // param1 （以及 this.prop）均为 string 类型
}

为代码添加 JSDoc 注释使得阅读和理解代码更加方便（代码交接时再也不用抓狂了，当然前提是注释写得好），也保障了开发时的体验并且降低了很多运行时才能发现的数据类型方面的 bug。VSCode 基本支持 JSDoc 的常见语法，具体使用可参见JSDoc support in JavaScript。

基于 TypeScript 类型声明文件

除了使用 JSDoc 提前声明类型，更为激进的做法是直接使用微软开发的 TypeScript，为整个项目带来完善的静态类型检查。当然，对于老项目来说，改造的成本较为巨大（使用 Flow 也类似，要动的代码太多，况且 Flow 烂尾了）。不过由于和 TypeScript 师出同门，VSCode 能够直接读取前者的类型声明文件，来为 JavaScript 提供智能提示（实际上 JavaScript 的智能提示功能就是基于 TypeScript 团队为 VSCode 提供的 JavaScript 语言服务开发的）。 TypeScript 的类型声明文件以 .d.ts 为后缀，用于描述同名的 JavaScript 文件导出代码的类型，功能上类似于 C 语言的 .h 头文件。不严格地来说，ts 类型声明文件就像用 TypeScript 语法将 JSDoc 的注释重写了一遍并提取到了多带带的文件中。VSCode 更是将二者作了融合，当你二者混用的时候，可以直接在 JSDoc 的注释中直接使用 ts 类型声明文件中定义的 interface 和 class 等。直接使用官方提供的示意图（图中是 Visual Studio，不过无伤大雅）：

对于自己的代码，可以编写对应的 ts 类型声明文件，而对于引用的第三方库，社区同样提供了解决方案：DefinitelyTyped 提供了常见的第三方库的类型声明文件。VSCode 有很多第三方库已经内置类型声明文件，自己下载的话直接使用 npm 即可：

# @types + 第三方库名称
npm i @types/express

关于 ts 类型声明文件的语法等相关信息，参见官网介绍。

另外，在 VSCode 中，类型检查并非默认开启，这意味着即使你有详尽的 JSDoc 注释或 ts 类型声明文件，依然可能在数据类型上栽跟头。开启方式为在项目根目录下添加 jsconfig.json 文件，并设置 "checkJs": true，示例如下：

{
    "compilerOptions": {
        "checkJs": true
    },
    
    // 位于此目录下的文件不进行静态检查和智能提示
    "exclude": [
        "node_modules",
        "**/node_modules/*"
    ]
}

总结

最后，无论是对老项目的改造或是新项目的开发，使用以上的方式添加智能提示和类型检查显而易见会略微拖慢开发速度，但我们认为，与智能提示带来的开发体验、将很多可能在运行时才能发现的错误通过类型检查前置解决、顺手完成的详细文档以及重构代码时的信心相比，这点速度的牺牲是值得的。

参考文档：

JavaScript in Visual Studio Code

Working with JavaScript

JavaScript Language Service in Visual Studio

GPU云服务器云服务器请检查你的网络或者防火墙设置静态类型检查基线检查添加白名单 js检查数据类型

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/102495.html

JS 静态类型检查工具 Flow

摘要：本文主要介绍了解决作为弱类型语言没有类型检查痛点的静态类型检查工具，并且介绍了在中使用的方法，最后介绍了一些常用的语法。本文主要介绍了解决JS作为弱类型语言没有类型检查痛点的静态类型检查工具 Flow ，并且介绍了在WebStorm中使用Flow的方法，最后介绍了一些常用的Flow语法。 1. 简介 JS作为一种脚本语言是没有类型检测的，这个特点有时候用着很方便，但在一个较大的项目中...

CloudDeveloper 2019-08-22 16:17 评论0 收藏0
vue2.0学习笔记（prop）

摘要：用一个变量进行动态赋值。传入一个对象即便对象是静态的，我们仍然需要来告诉这是一个表达式而不是一个字符串。我们可以将这个特性添加到你的组件实例上然后这个特性就会自动添加到的根元素上。 1、prop的大小写 HTML 中的特性名是大小写不敏感的，所以浏览器会把所有大写字符解释为小写字符。这意味着当你使用 DOM 中的模板时，camelCase (驼峰命名法) 的 prop 名需要使用其等价...

I_Am 2019-08-23 18:37 评论0 收藏0
2017前端性能优化清单

摘要：性能最好具有可量化可监测以及可改动的特性。下文是一份年的前端性能优化清单，阐述了作为前端开发人员，为了确保反馈速度以及浏览器兼容性我们需要考虑的问题。地图设计的决定违背了性能理念，所以他在这份清单内的顺序有待考虑。 2017前端性能优化清单你开始使用渐进启动了么？是不是已经使用过React和Angular中tree-shaking和code-splitting两个工具？有没有用过Br...

verano 2019-08-20 13:45 评论0 收藏0
2017前端性能优化清单

摘要：性能最好具有可量化可监测以及可改动的特性。下文是一份年的前端性能优化清单，阐述了作为前端开发人员，为了确保反馈速度以及浏览器兼容性我们需要考虑的问题。地图设计的决定违背了性能理念，所以他在这份清单内的顺序有待考虑。 2017前端性能优化清单你开始使用渐进启动了么？是不是已经使用过React和Angular中tree-shaking和code-splitting两个工具？有没有用过Br...

kycool 2019-08-30 15:52 评论0 收藏0
2017前端性能优化清单

摘要：性能最好具有可量化可监测以及可改动的特性。下文是一份年的前端性能优化清单，阐述了作为前端开发人员，为了确保反馈速度以及浏览器兼容性我们需要考虑的问题。地图设计的决定违背了性能理念，所以他在这份清单内的顺序有待考虑。 2017前端性能优化清单你开始使用渐进启动了么？是不是已经使用过React和Angular中tree-shaking和code-splitting两个工具？有没有用过Br...

CollinPeng 2019-08-01 16:12 评论0 收藏0