如何开发一款 JSSDK ？

最近由于项目需要，要开发一款 JSSDK，因为之前只有使用和二次开发JSSDK的经验，所以学习了一下相关的从零到一的只是。同时也看了360一位同行的文章，深有感触，故有此文。

JSSDK的定义与分类

什么是JSSDK

SDK是 Software Development Kit（软件开发工具包）的缩写，JSSDK是为了帮助前端实现特定需求，而向开发者暴露的一些JS-API的集合， 开发者可以通过它在网页中集成和使用某些特定的功能，例如社交分享、地图服务、支付功能等。

它通常包括以下的模块：

1. JavaScript库：这是 JSSDK 的核心部分，包含了一系列预先编写好的JS代码，这些代码实现了一些特定的功能，如用户认证、数据分析、社交分享等。

2. API 文档：这部分文档详细描述了如何使用 JSSDK 中的各个功能。它通常会包含函数和方法的列表，以及如何使用这些函数和方法。

3. 示例代码：这部分代码展示了如何在实际项目中使用 JSSDK。通过阅读和运行示例代码，开发者可以更好地理解如何使用 JSSDK。

JSSDK的分类

JSSDK 的分类主要取决于它们提供的功能和服务。通常根据其功能不同分为：UI组件库、JS工具库、分析统计SDK、社交媒体SDK

• UI组件库：通过封装一系列组件，通过配置帮助开发者调用，实现一些UI效果，例如：Antd、ElementUI、Vant、Bootstrap 等

• JS类库：通过实现一类常用的方法，便于开发处理数据，也不用再考虑兼容性，常用的如：lodash、moment、axios、jQuery 等

• 监控统计工具：通过API，来监听前端系统的报错、统计数据，以及数据上报等，例如：Sentry、百度统计、Google Analytics JSSDK 等

• 其他第三方的SDK：微信SDK、支付宝SDK、新浪微博SDK，Facebook JSSDK 等

如何设计JSSDK

设计SDK要遵循的原则

• 单一职责原则：SDK一般都是为了满足一类业务的需要，所以设计之初要明确业务范围，如果功能过于复杂，可以拆改成几个独立的SDK，在主SDK中引入相关逻辑就OK了，这样便于功能解耦和测试。

• 最小可用、最少依赖性原则：能用确定的方法实现，就不要再去搞复杂的内容。SDK要减少依赖，一些工具库能不用就不用。尽可能自行实现必要的方法，或者引入尽量少的库。否则会导致SDK打包后过大，或者更新版本带来的兼容问题。

• 稳定性原则：保持SDK足够的稳定性，一方面要保持API方法的稳定，另一方面在设计API的入参时，参数要用对象类型，这样便于后续扩展添加更多参数。如果SDK有升级要考虑兼容旧版本。新功能要新增API，旧的API不要删除。

• 易用性原则：要满足易用性原则，首先要有简洁的API，明确的方法注释、文档跟示例代码很重要，不管SDK写的多漂亮，使用者首先接触的是接入文档，然后是覆盖所有API的示例代码，一个好的实例代码能起到事半功倍的效果。

语言与构建工具选择

1. 语言的选择

   语言无非是选择TS还是JS,这里推荐使用TS来编写SDK代码因为相比JS而言他有如下优势：

   • 类型系统：TypeScript的最大特点就是它的类型系统。这个类型系统可以在编译阶段捕获许多常见的错误，如类型错误、未定义的函数或属性等，从而提高代码的质量和可维护性。

   • 更好的工具支持：由于TypeScript的类型信息，IDE 和编辑器可以提供更好的代码补全、自动提示等功能。

2. 构建工具的选择

   推荐使用Rollup来作为SDK项目的打包构建工具

   • Rollup的配置通常比Webpack更简单，更易于理解。这对于新手或者希望快速开始项目的开发者来说是一个优点。

   • 更好的Tree-shaking：Rollup 的Tree-shaking功能通常比Webpack更有效。Tree-shaking 是一种只包含实际使用的代码，而去除未使用代码的优化技术。这可以帮助减小最终打包文件的大小。

   • Rollup是以ES6模块标准为中心设计的，这使得它在处理ES6模块时更加高效。

   • 适合库的打包：由于Rollup的特性，它通常更适合用于打包库（library）或者工具，而Webpack则更适合用于打包应用（application）。

SDK核心功能的实现

这里要根据项目的用途来具体实现，不再赘述

发布、维护、更新

发布到CDN或是NPM

• CDN 发布

  为了便于用户使用，SDK要发布CDN与NPM上，打包完成后，js 文件要有一定的命名规范： [名称][prod/test][版本].js 将打包好的js文件进行发布到CDN，用户通过引入链接的形式进行访问

• NPM 发布

  需要注意的是，如果要将包发布到npm上，需要设置 package.json 的几个关键参数：

  • name: 名称

  • version：版本：遵循Major. Minor. Patch规范

  • description：描述

  • main：主文件

  • keywords：SDK搜索关键词

  • maintainers: 列表，维护者信息可以是多个

  最后执行登录和发布命令：

  npm login
  npm publish

维护与更新

SDK的维护更新关键是要做好两个关键文档的书写：SDK接入文档与SDK维护文档，这两个文档一个是对外的，便于开发者接入的文档，一个是对内的，便于项目开发者的维护文档，这两个文档需要包含以下内容：

• SDK 接入文档（对外）

  • SDK简介

  • SDK支持的平台

  • SDK接入方式：cdn & npm

  • SDK API的介绍：API简介&示例&参数说明

  • 示例代码：example

• SDK维护更新文档（对内）

  • SDK目录文件说明

  • 如何运行调试SDK

  • 打包发布SDK

  • SDK更新记录：版本&发布时间&cdn地址&更新内容

总结

开发一款 JavaScript SDK 需要考虑到诸多方面，除了以上提到的，SDK还需要考虑到用户友好性、性能、安全性、易用性等方面，这里就不展开了。 另外，一个SDK写的再好不如有个好文档，特别是对外的SDK接入文档，它可以为开发者提供更好的开发体验。