如何打造一款标准的JS-SDK

0 前言

本文主要介绍如何基于JavaScript来开发SDK，任何基于JS的场景均可以用相似的思路来解决，不管是移动端H5仍是服务端纯NodeJS。文中会说起一些设计原则以及实现技巧，并结合 岳鹰全景监控平台SDK 这个实际案例来展现如何应用它们。

1 SDK是什么

SDK全称是“Software Development Kit”，直译就是软件开发工具集。说的再通俗点就是一个面向开发者，针对特定领域的软件包。好比 Java SDK（JDK），就是一个Java领域的软件包。基于它，开发人员就能够快速构建本身的Java应用。比较规范的SDK通常都会包含若干的API、开发工具集和说明文档。

JS-SDK也无外于此，不过鉴于JS语言自己的特性，基于Ta封装的SDK更多常见于UI组件库、统计分析、web服务接口封装、前端稳定性和性能监控等场景。上一小节提到的 岳鹰全景监控平台SDK 即属于前端稳定性和性能监控这一领域范畴的SDK。

2 设计原则

如何设计SDK，其实更多取决于你的场景，或者SDK最终的用途。好比实现一个给网页调用的SDK与用于服务端的SDK就有明显的差别，但这之间确实存在着一些共通的原则，或者方法论：

• 最小可用性原则，即用最少的代码，如无必要勿增实体
• 最少依赖原则，即最低限度的外部依赖，如无必要勿增依赖

进一步阐述，即咱们打造的SDK要符合如下的要求

2.1 知足功能需求

SDK通常都是偏于面向某个领域，因此，同时在设计和实现的时候明确职责和边界很重要，同时还应该足够精简，专一领域内的业务。

2.2 足够稳定

• 毫不能致使宿主应用崩溃，这是最基础也是最严格的要求
• 较好的性能，好比SDK体积应尽可能小，运行速度尽可能快
• 可测试，保障每一次变动
• 向后兼容，不轻易出现 Breakchange

2.3 少依赖，易扩展

• 最小程度的第三方依赖，尽量自行实现，确实没法避免则最小化引入
• 插件化，最大限度支持扩展
• Hook机制，知足个性化诉求

3 如何实现

下面咱们将经过剖析 岳鹰前端监控SDK 的设计过程，来看看上述的设计原则是如何应用到实际的开发过程当中的。

3.1 明职责，定边界

前面章节提到， 岳鹰前端监控SDK 是前端稳定性和性能监控的SDK，主要面向前端H5领域。所以，稍加分析便可得出如下结论

• 前端领域，稳定性方面主要的关注点
  • JS异常
  • 资源加载异常
  • API请求异常
  • 白屏异常
• 性能方面，核心的关注点
  • 白屏时间
  • 可交互时间（TTI）
  • 首屏时间
  • FP / FMP / FCP 等

上述监控内容实际上都相对独立，所以咱们能够把Ta们横向划分为以下几大部分：

明确了SDK的边界以及各部分的职责，结合前端监控的特性，咱们能够开始设计SDK的总体框架了。

3.2 筑框架，夯基础

俗话说千里之行始于足下，所以筑牢基础十分重要。总得来讲，咱们须要作好下面几点

• 首先肯定SDK的引用形式

SDK总体而言是一个大模块，前端模块有多种表现形式：ES Module、CommonJS、AMD/CMD/UMD，而在引用方面则大致分 CDN和 NPM两种。即不管咱们实现的是哪一种形式的模块，最终都是经过CDN或者NPM的方式提供给用户引用。

import wpkReporter from 'wpkReporter'

// CommonJS
const wpkReporter = require('wpkReporter')

// AMD,requireJS引用
require.config({
  paths: {
    "wpk": "https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js",
  }
})
require(['wpk', 'test'], function (wpk) {
  // do your business
})
复制代码

乍看有点眼花，但事实上今时今日的前端工程领域，已有不少利器能够帮助咱们达到目的。好比 webpack，经过简单的配置就能够构建出一个UMD的bundle。

module.exports = {
  output: {
    filename: '[name].js',
    path: `${__dirname}/dist`,
    globalObject: 'this',
    library: '[name]',
    libraryTarget: 'umd'
  }
} 
复制代码

综上，咱们能够经过 webpack将 SDK构建为一个UMD bundle，这样能够自动适配全部形式的模块。同时咱们也将同时提供 CDN和 NPM两种引用方式，给用户更多选择。

• 肯定SDK的版本管理机制

现有较成熟的版本管理机制当属 语义化版本号 ，表现形式为 {主版本}.{次版本}.{补丁版本}，简单易记好管理。 通常重大的变动才会触发主版本号的更替，并且极可能新旧版本不兼容。次版本主要对应新特性或者较大的调整，所以也有可能出现breakchange。其余小的优化或bugfix就基本都是在补丁版本号体现。 看到此处，是否有点似曾相识的感受？没错，全部NPM模块都遵循语义化版本规范，所以结合第一点，咱们能够将SDK初始化为一个NPM模块，结合webpack的能力就能够实现基础的版本管理及模块构建。

• 肯定SDK的基础接口

接口是SDK和用户沟通的桥梁，每个接口对应着一个独立的SDK功能，而且有明确的输入和输出。咱们能够先来看看岳鹰前端监控SDK的核心接口有哪些？

wpk.report(logData)
wpk.reportJSError(error)
wpk.reportAPIError(apiData)
// 配置变动
wpk.setConfig(data)
// SDK诊断
wpk.diagnose()
// 添加插件
wpk.addPlugin(plugin)
复制代码

总结接口的设计原则，以下

• 职责单一

一个接口只作一件事情

• 命名简单清晰，参数尽可能少但可扩展

好的接口命名就是最好的注释，一看即明其用处 参数尽量适用 Object封装

• 作好参数校验和逻辑保护

3.3 领域分析，模块划分

定边界的时候，咱们已经清楚划分了SDK的几个关键的部分：全局异常、API异常、页面性能和白屏，实际上监控SDK一般也会内置对页面流量的监控，以方便用户对异常的影响面作出评估。这几个核心的关键组成部分，每一块都对应一个专业的领域，所以对应到SDK也是每个独立的模块。 除了这些核心的偏领域的模块，SDK还须要有更基础的与领域无关的模块，包括SDK内核(构造方法、插件机制、与下游服务的交互、上报队列机制、不一样环境的管理等等)和工具类库。 咱们能够先看一下岳鹰前端监控SDK最后的总体模块划分：

• SDK底层提供基础的能力，包括上面提到的内核、插件机制的实现、工具类库以及暴露给用户的基础API
• 能够看到，咱们前面提到的全部模块都以插件的形式存在，即各领域的功能都各自松散的作实现，这样使得底层能力更具通用性，同时扩展能力也更强，用户甚至也能够封装本身的插件。
• Biz部分更可能是对于不一样宿主环境的多入口适配，当前支持浏览器、Weex以及NodeJS。

3.4 测试覆盖，线上无忧

SDK是一个基础服务，相对于前台业务而言可能更底层些。其影响面跟应用的范围是正比的关系，更多的用户意味着更大的责任。因此SDK的质量保障也是很重要的一个环节。 岳鹰前端监控SDK的质量保障策略很简单，只有两条

• 核心接口100%的单元测试覆盖率
• 发布卡点：再小的版本发布也须要走集成测试回归

事实上，除了核心接口，工具类库的全部功能咱们都实现了 100%的单元测试覆盖，咱们采用的前端测试工具是轻量好用的 Jest 。

test('isError: real error', function () {
  var err = new Error('this is an error')
  expect(util.isError(err)).toBeTruthy()
})
复制代码

3.5 细节打磨，极致体验

• 快捷引入
  • 极尽所能提升用户引用的效率
  • 一行代码，快速引入，享用监控全家桶功能

<script>
  !(function(c,i,e,b){var h=i.createElement("script");var f=i.getElementsByTagName("script")[0];h.type="text/javascript";h.crossorigin=true;h.onload=function(){c[b]||(c[b]=new c.wpkReporter({bid:"dta_1_203933078"}));c[b].installAll()};f.parentNode.insertBefore(h,f);h.src=e})(window,document,"https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js","__wpk");
</script>
复制代码

• 动态采样

  • 即经过云端下发数据采样率的方式，控制客户端上报数据的频率
  • 更好的保护监控下游

• 自我诊断

  • 除了接口，SDK总体对用户而言就是一个黑盒，所以用户在遇到问题时很容易蒙圈 (如：为啥没有上报数据)
  • SDK能够提供一个自我诊断的接口，快速排除基础问题
    • 好比，SDK是否已正常初始化、关键参数是否正常设置等

• 增长调试模式，输出更详细的过程日志，方便定位问题

• 渐进式的指引文档

  • 图文并茂，按部就班
  • 入门，一步步引导用户初识SDK，领略概貌，学会基本的使用
  • 进阶，安利SDK的深度用法，帮助用户更好的使用SDK

4 结语

实际在SDK的设计和开发过程当中，要处理的问题还远不止本文所述的内容，好比 NPM模块开发时本地如何引用，构建的bundle大小如何调优等等。不过仍是但愿阅完此文，对你有所启发。同时文中如有不对之处，还望不吝赐教。

访问岳鹰全景监控平台