port_to

上次写文章已经是一年前了, 来拔下草...

前言

维护一个有几年历史的 JavaScript 项目是非常辛苦的（如果碰巧这个项目之前的开发不怎么喜欢写文档和注释, 就更难了）。

假设你需要给里面一部分功能打些补丁, 那么你常常就会面对如下场景：WTF这个对象有啥属性? 通过一堆console.log和断点调试终于搞定了, 发誓再也不碰这段代码了。

几个月以后又有需求需要在这里打些补丁, 然后就会再次出现：WTF这个对象有啥属性? ...

也想过引入 TypeScript 来解决以上问题, 它能提供 IDE 自动补全还有最重要的类型安全。但是面对 1000+ 个 js 文件, 算了算了。

这篇文章提供了一种渐进式引入 TypeScript 的方式, 可供大家参考。

给 JavaScript 加上「类型注释」

秘诀就是JSDoc, 其实很多 JavaScript 代码编辑器都支持 JSDoc, 比如我常用的 Visual Studio Code 和 Webstorm 。

下面用一个案例来介绍具体怎么使用 JSDoc 。

一个原始 JavaScript 文件

假设我们有一个 meeting.js 文件, 描述了如何将成员渲染到页面上。里面大致代码如下：

// meeting.js

// 成员
let members = [{
    id: '001', nickName: 'wang', role = 'speaker'
}];
// 视频流
let streams = {
    '001': MagicStreamObject()
};

function renderMeetingMembers(members, streamSources) {
    // 发言人
    let speakers = members.filter(x => x.role === 'speaker');
    // 其他人
    let others = members.filter(x => x.role !== 'speaker');

    // 将成员与流关联起来
    speakers.forEach(speaker => {
        let stream = streams[speaker.id];
        if (stream) {
            speaker.stream = stream;
        }
    });

    // 非常复杂的渲染逻辑
    renderMembers(speakers, others);
}

renderMeetingMembers(members, streams);

要给上面这个文件加上「类型注释」应该怎么做呢?

定义一个 .d.ts 文件

因为上面两个代码编辑器都默认支持 TS 文件, 那么我们可以方便的在项目里新建任意 TS 文件。里面大致代码如下

// meeting.d.ts
export interface MagicStream {
    play: () => void;
    stop: () => void;
};

export type Member {
    id: string;
    nickName: string;
    role: 'speaker' | 'role';
    stream?: MagicStream;
};

至于什么时候用 type, 什么时候用 interface 随便你...

引入类型并标注

第一步, 引入类型。使用 @typedef 和 import

// meeting.js
/** @typedef {import('./meeting.d.ts').MagicStream} MagicStream */
/** @typedef {import('./meeting.d.ts').Member} Member */

第二步, 用 @type 给普通变量加上类型

/** @type {Member[]} */
let members = [{ id: '001', nickName: 'wang', role = 'speaker' }];
/** @type {{ [userId: string]: MagicStream }} */
let streams = {
    '001': MagicStreamObject()
};

第三步, 给函数参数加上注释

/**
 * @param {Member[]}  members - 参会成员
 * @param {{ [userId: string]: MagicStream }}  streamSources - 流
 **/
function renderMeetingMembers(members, streamSources) {
    // blabla
}

做完这几步以后基本上编辑器就能自动补全代码了！！！

引入 TSC

随着 d.ts 文件积累越来越多，是时候开始真正引入 TSC 来编译整个项目了。

去网上随便抄个教程吧，注意关键点是 tsconfig.json 里面有个重要选项：allowJS - 混写 JavaScript 和 TypeScript 。

把 js 文件换成 ts

没啥特别的难度, 一点点修复警告⚠️。实在不行 any 大法好！！！

The Copy Monkey