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

Vue中文社区

作者:茶什i

https://developer.aliyun.com/article/777451

岳鹰全景监控,是阿里UC官方出品的先进移动应用线上监控平台,为开发者及企业提供一套完整的移动应用线上质量监控解决方案。岳鹰WEB前端监控,可实时监控页面性能、JS异常、资源加载异常、API成功率、自定义错误等异常情况。本文通过岳鹰前端监控SDK的实际案例,介绍如何基于JavaScript来开发SDK,并分享一些设计原则以及实现技巧。

SDK 是什么
SDK全称是“Software Development Kit”,直译就是软件开发工具集。说的再通俗点就是一个面向开发者,针对特定领域的软件包。比如Java SDK(JDK),就是一个Java领域的软件包。基于它,开发人员就可以快速构建自己的Java应用。比较规范的SDK一般都会包含若干的API、开发工具集和说明文档。
JS SDK也无外于此,不过鉴于JS语言本身的特性,基于Ta封装的SDK更多常见于UI组件库、统计分析、web服务接口封装、前端稳定性和性能监控等场景。岳鹰前端监控SDK[1]即属于前端稳定性和性能监控这一领域范畴的SDK。
设计原则
如何设计SDK,其实更多取决于你的场景,或者SDK最终的用途。比如实现一个给网页调用的SDK与用于服务端的SDK就有明显的差异,但这之间确实存在着一些共通的原则,或者方法论:
  • 最小可用性原则,即用最少的代码,如无必要勿增实体。

  • 最少依赖原则,即最低限度的外部依赖,如无必要勿增依赖。

进一步阐述,即我们打造的SDK要符合以下的要求。

满足功能需求

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

足够稳定

  • 绝不能导致宿主应用崩溃,这是最基础也是最严格的要求。

  • 较好的性能,比如SDK体积应尽量小,运行速度尽量快。

  • 可测试,保障每一次变更。

  • 向后兼容,不轻易出现 Breakchange。

少依赖,易扩展

  • 最小程度的第三方依赖,尽可能自行实现,确实无法避免则最小化引入。

  • 插件化,最大限度支持扩展。

  • Hook机制,满足个性化诉求。

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

明职责,定边界

前面章节提到,岳鹰前端监控SDK是前端稳定性和性能监控的SDK,主要面向前端H5领域。因此,稍加分析即可得出以下结论:
  • 前端领域,稳定性方面主要的关注点

  • JS异常

  • 资源加载异常

  • API请求异常

  • 白屏异常

  • 性能方面,核心的关注点

  • 白屏时间

  • 可交互时间(TTI)

  • 首屏时间

  • FP / FMP / FCP 等

上述监控内容实际上都相对独立,因此我们可以把它们横向划分为如下几大部分:
明确了SDK的边界以及各部分的职责,结合前端监控的特性,我们可以开始设计SDK的整体框架了。

筑框架,夯基础

俗话说千里之行始于足下,因此筑牢基础十分重要。总得来说,我们需要做好下面几点:
确定SDK的引用形式
SDK整体而言是一个大模块,前端模块有多种表现形式:ES Module、CommonJS、AMD/CMD/UMD,而在引用方面则大体分 CDN和 NPM两种。即无论我们实现的是哪种形式的模块,最终都是通过CDN或者NPM的方式提供给用户引用。
    // ES Moduleimport wpkReporter from 'wpkReporter'// CommonJSconst 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。
      // webpack.config.jsmodule.exports = {  output: {    filename: '[name].js',    path: `${__dirname}/dist`,    globalObject: 'this',    library: '[name]',    libraryTarget: 'umd'  }}
      综上,我们可以通过webpack将SDK构建为一个UMD bundle,这样可以自动适配所有形式的模块。同时我们也将同时提供CDN和NPM两种引用方式,给用户更多选择。
      确定SDK的版本管理机制
      现有较成熟的版本管理机制当属语义化版本号[2],表现形式为 {主版本}.{次版本}.{补丁版本},简单易记好管理。
      一般重大的变更才会触发主版本号的更替,而且很可能新旧版本不兼容。次版本主要对应新特性或者较大的调整,因此也有可能出现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封装

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

        领域分析,模块划分

        定边界的时候,我们已经清楚划分了SDK的几个关键的部分:全局异常、API异常、页面性能和白屏,实际上监控SDK通常也会内置对页面流量的监控,以方便用户对异常的影响面做出评估。这几个核心的关键组成部分,每一块都对应一个专业的领域,因此对应到SDK也是每一个独立的模块。
        除了这些核心的偏领域的模块,SDK还需要有更基础的与领域无关的模块,包括SDK内核(构造方法、插件机制、与下游服务的交互、上报队列机制、不同环境的管理等等)和工具类库。
        我们可以先看一下岳鹰前端监控SDK最后的整体模块划分:
        • SDK底层提供基础的能力,包括上面提到的内核、插件机制的实现、工具类库以及暴露给用户的基础API。

        • 可以看到,我们前面提到的所有模块都以插件的形式存在,即各领域的功能都各自松散的做实现,这样使得底层能力更具通用性,同时扩展能力也更强,用户甚至也可以封装自己的插件。

        • Biz部分更多是对于不同宿主环境的多入口适配,当前支持浏览器、Weex以及NodeJS。

        测试覆盖,线上无忧

        SDK是一个基础服务,相对于前台业务而言可能更底层些。其影响面跟应用的范围是正比的关系,更多的用户意味着更大的责任。所以SDK的质量保障也是很重要的一个环节。
        岳鹰前端监控SDK的质量保障策略很简单,只有两条:
        • 核心接口100%的单元测试覆盖率

        • 发布卡点:再小的版本发布也需要走集成测试回归

        事实上,除了核心接口,工具类库的所有功能我们都实现了100%的单元测试覆盖,我们采用的前端测试工具是轻量好用的Jest[3]。
          // 小巧精炼的 Jest,笔者力荐test('isError: real error', function () {  var err = new Error('this is an error')  expect(util.isError(err)).toBeTruthy()})

          细节打磨,极致体验

          • 快捷引入

          • 极尽所能提高用户引用的效率

          • 一行代码,快速引入,享用监控全家桶功能

            <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

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

            [1]https://yueying-docs.effirst.com/api-usage.html

            [2]https://semver.org/

            [3]https://jestjs.io/

            (0)

            相关推荐

            • 手把手带你入门前端工程化——超详细教程

              本文将分成以下 7 个小节: 技术选型 统一规范 测试 部署 监控 性能优化 重构 部分小节提供了非常详细的实战教程,让大家动手实践. 另外我还写了一个前端工程化 demo 放在github上.这个 ...

            • anyproxy学习2-rule模块实现接口mock功能

              前言 AnyProxy不仅仅可以抓包,还可以拦截请求并修改服务端响应,实现接口mock功能. 面试时候经常会问到第三方支付如何测试这种,如果对接的第三方没提供测试环境,那么就需要搭建一个mock服务器 ...

            • 如何打造一款标准的JS SDK?

              阿里妹导读:岳鹰全景监控,是阿里UC官方出品的先进移动应用线上监控平台,为开发者及企业提供一套完整的移动应用线上质量监控解决方案.岳鹰WEB前端监控,可实时监控页面性能.JS异常.资源加载异常.API ...

            • 奶茶店为什么热衷于要设计、打造爆款IP产品?

              奶茶店什么是爆款IP产品? 爆款是指在商品销售中,供不应求,销售量很高的商品.通常所说的卖的很多,人气很高的商品.广泛应用于网店,实物店铺.近义词,牛品,爆款商品,爆款宝贝,人气宝贝,热卖商品. 如果 ...

            • 网店一直没生意,如何打造爆款,提高销量?

              很多人开网店,非常努力,该做的都做了,可是网店一直没有生意.李老师想说的是,可能是你努力的方向错了,方向不对,努力白费!在淘宝上想要把店铺的流量做起来有很多方法,比如打造一个爆款,可以很快的把店铺的流 ...

            • 如何打造爆款短视频?五招帮你轻松上热门,赶紧来看看

              如何打造爆款短视频?五招帮你轻松上热门,赶紧来看看.全民短视频时代,几乎人人都用手机刷各种短视频,毋庸置疑,现在短视频已经霸占了人们的碎片化时间,人们的需求越来越多样化,短视频泛滥的今天,有趣.有价值 ...

            • 【无线电史话】1961年,动手打造一款万宝路香烟盒大小四晶体管收音机难度有多大?

              1961年,自己动手打造一款便携式四晶体管口袋袖珍无线电接收机难度有多大? 60年前,1961年5月发行的<Radio Electronics>杂志展示了如何组装这种四晶体管袖珍收音机.这 ...

            • 4000字小红书视频笔记运营干货,教你快速打造爆款笔记

              2021年仍然是短视频快速发展的一年,小红书平台也给予了短视频笔记巨大的流量扶持. 根据千瓜数据统计,视频笔记在近7天.近1个月.半年内.近一年的笔记最高赞和热度笔记前十条平均点赞数量都高于图文笔记. ...

            • 2021-04-13周总《如何打造爆款,用什么产品引流》

              2021-04-13 哈喽!大家好,我是金州小吴 周总<如何打造爆款,用什么产品引流> 85度c不是卖咖啡,而是靠面包盈利的,它跟星巴克的差异化就在这里. 星巴克的经营方式是"小 ...

            • 微信商城,3分钟开店,分销+直播打造爆款商城

              随着微信商城模式逐渐成为电商标配,越来越多人选择创建微信商城,那么要想在众多商城中脱颖而出,势必要在系统模式上多下功夫,比如说直播电商+分销电商. 直播电商最开始是以平台为中心,运营点是依靠价格低廉和 ...

            • 正确的分析淘宝运营竞争对手,提高打造爆款率80%

              淘宝运营最讨厌的是同行来研究自己,但是自己又非常喜欢研究同行,因为同行就是师傅,非常有参考价值 我们分析同行需要从店铺装修.人群.产品布局.流量结构等,具体产品就有价格.卖点.详情.营销方案.引流关键 ...