专栏名称: Fundebug

Fundebug为JavaScript、微信小程序及Node.js开发团队提供专业的线上代码bug监控和智能分析服务。

2020年如何写一个现代的JavaScript库

Fundebug · 公众号 · 前端 · 2018-10-15 10:04

正文

我写过一些开源项目，在开源方面有一些经验，最近开到了阮老师的微博，深有感触，现在一个开源项目涉及的东西确实挺多的，特别是对于新手来说非常不友好

最近我写了一个jslib-base，旨在从多方面快速帮大家搭建一个标准的js库，本文将已jslib-base为例，介绍写一个开源库的知识

jslib-base 最好用的js第三方库脚手架，赋能js第三方库开源，让开发一个js库更简单，更专业

文档

所谓代码未动，文档先行，文档对于一个项目非常重要，一个项目的文档包括

README.md
TODO.md
CHANGELOG.md
LICENSE
doc

README.md

README是一个项目的门面，应该简单明了的呈现用户最关心的问题，一个开源库的用户包括使用者和贡献者，所以一个文档应该包括项目简介，使用者指南，贡献者指南三部分

项目简介用该简单介绍项目功能，使用场景，兼容性的相关知识，这里重点介绍下徽章，相信大家都见过别人项目中的徽章，如下所示

徽章通过更直观的方式，将更多的信息呈现出来，还能够提高颜值，有一个网站专门制作各种徽章，可以看这里

这里有一个README的完整的例子

TODO.md

TODO应该记录项目的未来计划，这对于贡献者和使用者都有很重要的意义，下面是TODO的例子

- [X] 已完成
- [ ] 未完成

CHANGELOG.md

CHANGELOG记录项目的变更日志，对项目使用者非常重要，特别是在升级使用版本时，CHANGELOG需要记录项目的版本，发版时间和版本变更记录

## 0.1.0 / 2018-10-6

- 新增xxx功能
- 删除xxx功能
- 更改xxx功能

LICENSE

开源项目必须要选择一个协议，因为没有协议的项目是没有人敢使用的，关于不同协议的区别可以看下面这张图（出自阮老师博客），我的建议是选择MIT或者BSD协议

doc

开源项目还应该提供详细的使用文档，一份详细文档的每个函数介绍都应该包括如下信息：

函数简单介绍

函数详细介绍

函数参数和返回值（要遵守下面的例子的规则）

- param {string} name1 name1描述
- return {string} 返回值描述

举个例子（要包含代码用例）

// 代码

特殊说明，比如特殊情况下会报错等

构建

理想的情况如下：

库开发者美滋滋的写ES6+的代码；
库使用者能够运行在浏览器（ie6-11）和node（0.12-10）中
库使用者能够使用AMD或CMD模块方案
库使用者能够使用webpack、rollup或fis等预编译工具

理想很丰满，现实很。。。，如何才能够让开发者和使用者都能够开心呢，jslib-base通过babel+rollup提供了解决方案

编译

通过babel可以把ES6+的代码编译成ES5的代码，babel经理了5到6的进化，下面一张图总结了babel使用方式的变迁

本文不讨论babel的进化史（后面会单独开一片博文介绍），而是选择最现代化的 babel-preset-env 方案，babel-preset-env可以通过提供提供兼容环境，而决定要编译那些ES特性

其原理大概如下，首先通过ES的特性和特性的兼容列表计算出每个特性的兼容性信息，再通过给定兼容性要求，计算出要使用的babel插件

首先需要安装 babel-preset-env

$ npm i --save-dev babel-preset-env

然后新增一个.babelrc文件，添加下面的内容

{
  "presets": [
    ["env",
    {
      "targets": {
        "browsers": "last 2 versions, > 1%, ie >= 6, Android >= 4, iOS >= 6, and_uc > 9",
        "node": "0.10"
      },
      "modules": false,
      "loose": false
    }]
  ]
}

targets 中配置需要兼容的环境，关于浏览器配置对应的浏览器列表，可以从browserl.ist上查看

modules 表示编出输出的模块类型，支持”amd”,”umd”,”systemjs”,”commonjs”,false这些选项，false表示不输出任何模块类型

loose 代表松散模式，将loose设置为true，能够更好地兼容ie8以下环境，下面是一个例子（ie8不支持 Object.defineProperty ）

// 源代码
const aaa = 1;
export default aaa;

// loose false
Object.defineProperty(exports, '__esModule', {
    value: true
});
var aaa = 1;
exports.default = 1;

// loose true
exports.__esModule = true;
var aaa = 1;
exports.default = 1;

babel-preset-env 解决了语法新特性的兼容问题，如果想使用api新特性，在babel中一般通过babel-polyfill来解决，babel-polyfill通过引入一个polyfill文件来解决问题，这对于普通项目很实用，但对于库来说就不太友好了

babel给库开发者提供的方案是 babel-transform-runtime ，runtime提供类似程序运行时，可以将全局的polyfill沙盒化

首先需要安装 babel-transform-runtime

$ npm i --save-dev babel-plugin-transform-runtime

在.babelrc增加下面的配置

"plugins": [
  ["transform-runtime", {
    "helpers": false,
    "polyfill": false,
    "regenerator": false,
    "moduleName": "babel-runtime"
  }]
]

transform-runtime，支持三种运行时，下面是polyfill的例子

// 源代码
var a = Promise.resolve(1);

// 编译后的代码
var _promise = require('babel-runtime/core-js/promise');

var a = _promise.resolve(1); // Promise被替换为_promise

虽然虽然可以优雅的解决问题，但是引入的文件非常之大，比如只用了ES6中数组的find功能，可能就会引入一个几千行的代码，我的建议对于库来说能不用最好不用

打包

编译解决了ES6到ES5的问题，打包可以把多个文件合并成一个文件，对外提供统一的文件入口，打包解决的是依赖引入的问题

rollup vs webpack

我选择的rollup作为打包工具，rollup号称下一代打包方案，其有如下功能

依赖解析，打包构建
仅支持ES6模块
Tree shaking

webpack作为最流行的打包方案，rollup作为下一代打包方案，其实一句话就可以总结二者的区别：库使用rollup，其他场景使用webpack

为什么我会这么说呢？下面通过例子对比下webpack和rollup的区别

假设我们有两个文件，index.js和bar.js，其代码如下

bar.js对外暴漏一个函数 bar

export default function bar() {
  console.log('bar')
}

index.js引用bar.js

import bar from './bar';

bar()

下面是webpack的配置文件webpack.config.js

const path = require('path');

module.exports = {
    entry: './src/index.js',
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: 'bundle.js'
    }
};

下面来看一下webpack打包输出的内容，o(╯□╰)o，别着急，我们的代码在最下面的几行，上面这一大片代码其实是webpack生成的简易模块系统，webpack的方案问题在于会生成很多冗余代码，这对于业务代码来说没什么问题，但对于库来说就不太友好了

注意：下面的代码基于webpack3，webpack4增加了scope hoisting，已经把多个模块合并到一个匿名函数中

/******/
(function(modules) { // webpackBootstrap
    /******/ // The module cache
    /******/
    var installedModules = {};
    /******/
    /******/ // The require function
    /******/
    function __webpack_require__(moduleId) {
        /******/
        /******/ // Check if module is in cache
        /******/
        if (installedModules[moduleId]) {
            /******/
            return installedModules[moduleId].exports;
            /******/
        }
        /******/ // Create a new module (and put it into the cache)
        /******/
        var module = installedModules[moduleId] = {
            /******/
            i: moduleId,
            /******/
            l: false,
            /******/
            exports: {}
            /******/
        };
        /******/
        /******/ // Execute the module function
        /******/
        modules[moduleId].call(module.exports, module, module.exports, __webpack_require__);
        /******/
        /******/ // Flag the module as loaded
        /******/
        module.l = true;
        /******/
        /******/ // Return the exports of the module
        /******/
        return module.exports;
        /******/
    }
    /******/
    /******/
    /******/ // expose the modules object (__webpack_modules__)
    /******/
    __webpack_require__.m = modules;
    /******/
    /******/ // expose the module cache
    /******/
    __webpack_require__.c = installedModules;
    /******/
    /******/ // define getter function for harmony exports
    /******/
    __webpack_require__.d = function(exports, name, getter) {
        /******/
        if (!__webpack_require__.o(exports, name)) {
            /******/
            Object.defineProperty(exports, name, {
                /******/
                configurable: false,
                /******/
                enumerable: true,
                /******/
                get: getter
                /******/
            });
            /******/
        }
        /******/
    };
    /******/
    /******/ // getDefaultExport function for compatibility with non-harmony modules
    /******/
    __webpack_require__.n = function(module) {
        /******/
        var getter = module && module.__esModule ?
            /******/
            function getDefault() { return module['default']; } :
            /******/
            function getModuleExports() { return module; };
        /******/
        __webpack_require__.d(getter, 'a', getter);
        /******/
        return getter;
        /******/
    };
    /******/
    /******/ // Object.prototype.hasOwnProperty.call
    /******/
    __webpack_require__.o = function(object, property) { return Object.prototype.hasOwnProperty.call(object, property); };
    /******/
    /******/ // __webpack_public_path__
    /******/
    __webpack_require__.p = "";
    /******/
    /******/ // Load entry module and return exports
    /******/
    return __webpack_require__(__webpack_require__.s = 0);
    /******/
})
/************************************************************************/
/******/
([
    /* 0 */
    /***/
    (function(module, __webpack_exports__, __webpack_require__) {

        "use strict";
        Object.defineProperty(__webpack_exports__, "__esModule", { value: true });
        /* harmony import */
        var __WEBPACK_IMPORTED_MODULE_0__bar__ = __webpack_require__(1);

        Object(__WEBPACK_IMPORTED_MODULE_0__bar__["a" /* default */ ])()

        /***/
    }),
    /* 1 */
    /***/
    (function(module, __webpack_exports__, __webpack_require__) {

        "use strict";
        /* harmony export (immutable) */
        __webpack_exports__["a"] = bar;

        function bar() {
            //
            console.log('bar')
        }

        /***/
    })
    /******/
]);

下面来看看rollup的结果，rollup的配置和webpack类似

export default {
    input: 'src/index.js',
    output: {
        file: 'dist/bundle2.js',
        format: 'cjs'
    }
};

下面看看rollup的产出，简直完美有没有，模块完全消失了，rollup通过顺序引入到同一个文件来解决模块依赖问题，rollup的方案如果要做拆包的话就会有问题，因为模块完全透明了，但这对于库开发者来说简直就是最完美的方案

'use strict';

function bar() {
  //
  console.log('bar');
}

bar();

模块化方案

在ES6模块化之前，JS社区探索出了一些模块系统，比如node中的commonjs，浏览器中的AMD，还有可以同时兼容不同模块系统的UMD，如果对这部分内容感兴趣，可以看我之前的一篇文章《 JavaScript模块的前世今生》

对于浏览器原生，预编译工具和node，不同环境中的模块化方案也不同；由于浏览器环境不能够解析第三方依赖，所以浏览器环境需要把依赖也进行打包处理；不同环境下引用的文件也不相同，下面通过一个表格对比下

	浏览器（script,AMD,CMD）	预编译工具（webpack,rollup,fis）	Node
引用文件	index.aio.js	index.esm.js	index.js
模块化方案	UMD	ES Module	commonjs
自身依赖	打包	打包	打包
第三方依赖	打包	不打包	不打包

注意: legacy模式下的模块系统可以兼容ie6-8，但由于rollup的一个bug（这个bug是我发现的，但rollup并不打算修复，╮(╯▽╰)╭哎），legacy模式下，不可同时使用 export 与 export default

tree shaking

rollup是天然支持tree shaking，tree shaking可以提出依赖模块中没有被使用的部分，这对于第三方依赖非常有帮助，可以极大的降低包的体积

举个例子，假设index.js只是用了第三方包is.js中的一个函数 isString ，没有treeshaking会将is.js全部引用进来

而使用了treeshaking的话则可以将is.js中的其他函数剔除，仅保留 isString 函数

规范

无规矩不成方圆，特别是对于开源项目，由于会有多人参与，所以大家遵守一份规范会事半功倍

编辑器规范

首先可以通过 .editorconfig 来保证缩进、换行的一致性，目前绝大部分浏览器都已经支持，可以看这里

下面的配置设置在js，css和html中都用空格代替tab，tab为4个空格，使用unix换行符，使用utf8字符集，每个文件结尾添加一个空行

root = true

[{*.js,*.css,*.html}]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
insert_final_newline = true

[{package.json,.*rc,*.yml}]
indent_style = space
indent_size = 2

代码风格

其次可以通过eslint来保证代码风格一致，关于eslint的安装和配置这里不再展开解释了，在jslib-base中只需要运行下面的命令就可以进行代码校验了，eslint的配置文件位于 config/.eslintrc.js

$ npm run lint

设计规范

eslint只能够保证代码规范，却不能保证提供优秀的接口设计，关于函数接口设计有一些指导规则

参数数量

函数的参数个数最多不要超过5个

可选参数

可选参数应该放到后面
可选参数数量超过三个时，可以使用对象传入
可选参数，应该提供默认值

参数校验与类型转换

必传参数，如果不传要报错
对下列类型要做强制检验，类型不对要报错（object, array, function）
对下列类型要做自动转换（number, string, boolean）
对于复合类型的内部数据，也要做上面的两个步骤
对于number转换后如果为NaN，要做特殊处理（有默认值的赋值为默认值，无默认值的要报错）