# sdk

**Repository Path**: sohucw/sdk

## Basic Information

- **Project Name**: sdk
- **Description**: 前端如何开发一个sdk
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2023-11-09
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 一、前言

如何开发一款 `js-sdk`，所以就做了一些调研，记录下开发过程。

> 前端SDK是什么？前端SDK是为了帮助前端实现特定需求，而向开发者暴露的一些JS-API的集合，规范的SDK包括若干API实现、说明文档等

前端SDK其实很常见了，比如：
- UI组件库：通过封装一系列组件，通过配置帮助开发者调用
    - Antd
    - ElementUI
- JS类库：通过实现一类常用的方法，便于开发处理数据，也不用再考虑兼容性
    - lodash
    - moment
- 监控统计工具：通过API，来监听前端系统的报错、统计数据
    - Sentry
    - 百度统计等
    
## 二、开发前的设计

> SDK开发其实很简单，简单到写一个函数导出就行，但在实际应用的过程中，我们要考虑很多实际情况。

### 1、设计原则
#### 满足一类功能的需要
SDK一般都是为了满足一类业务的需要，所以设计之初要明确业务范围

#### 最小可用性原则
即能用确定的方法实现，就不要再去搞复杂的内容。我理解，比如获取DOM，如果`GetElementById`可以实现，就不要再设计一下`GetElementsByTagName`、 `document.querySelector`等方法封装，除非有其他的开发需要无法满足。

#### 最少依赖原则
SDK减少依赖，要避免Lodash、JQuery、Moment、Dayjs等库，尽可能自行实现必要的方法，或者引入尽量小的库。否则会导致SDK打包后过大，或者更新版本带来的兼容问题，能用原生的方法尽量使用原生的

**当然一切都要根据实际情况，有些SDK是时间的各种处理，自己处理时间的成本太高，不妨引入小型的Dayjs时间库**

#### 足够稳定、向后兼容
减少BreakChange，绝不能导致载体应用崩溃，同时做好文档说明

#### 易扩展
模块化实现方法，尽量小的封装函数，保持函数功能的单一性原则，这样就可以更好的增加SDK的能力。

根据这些原则，下面是我们做的对应操作：

### 2、要实现的功能

首先要明确我们写的SDK是用来做什么的？

比如我本次实现的是用户H5页面的一键登录和号码检测。

那么我们需要暴露两个实例，供其他开发者使用，为了满足易扩展的原则，我们将声明两个类，来实现（如果每个实例都很多能力，可以拆分成两个SDK也是可以的）

### 3、构建工具和技术选择

提供的SDK一般都要提供压缩和未压缩版本，未压缩可以用来帮助开发调用，查找问题。压缩版本可以使用在生产环境，减少http损耗。所以我们要借助构建工具来集成这部分的能力。

可供选择的压缩工具有很多：webpack、Rollup、Gulp

如果是纯类库的压缩，当然是Rollup更好，压缩更彻底 Vue的源码是Rollup打包的。

如果是有DOM和样式，那么使用webpack功能更强大

这里由于我们可能涉及到页面SDK，而且对Webpack更熟悉，所以选择Webpack

### 4、单元测试(这块可以不写)

SDK的设计原则有一条：足够稳定、向后兼容，最少依赖原则。

这就意味着我们要少写Bug，所以一定要引入单元测试，这里我们选择Jest，使用起来也很简单。

```js
describe('common test', () => {
    test('isIOS', () => {
        expect(isIOS()).toBeBoolean(true, false);
    })
    test("isWifi", () => {
        expect(isWifi()).toBeBoolean(true, false);
    })
})
```

### 5、SDK支持的引入方式

浏览器js模块化常见的几种方式包括：amd\cmd\es6 modules\umd

- 1、静态资源引入
```
<script src="/sdk/v1/sdk"></script>
```
- 2、支持amd引入

```
define([vue.js, lodash.js], function($, _){
    console.log("vue and lodash", $, _)
})
```
- 3、支持cmd引入
```js
define(function(require){
    const lodash = require('./a.js')
    console.log("lodash", lodash)
})
```
- 4、支持es6引入
```
import { sdk } from 'sdk'
```
我们直接在webpack中配置umd方式打包，然后就可以支持上面的多种引入方式

```js
output: {
    path: path.resolve(__dirname, '../dist'),
    filename: '[name].js',
    library: 'DWSDK',
    libraryTarget: 'umd'
}
```
打包的库命名：`DWSDK`

### 6、版本维护和更新

- 管理好版本号
- 记录好更新日志

SDK版本更新，每个版本都会存在差异，而用户使用的版本肯定也太一样，所以记录好版本更新日志可以减少非技术问题。

通过静态文件导出的SDK要同时部署多个版本，不能随时下线老版本。

### 7、其他的注意点
- 代码混淆
- 开发环境配置和代码格式
- 上传NPM
- CDN部署
- 依赖的三方库如何打包进SDK
    - 仅支持静态引入的库如何处理
    - 如何全局共享库方法
- 针对有后端API交互的SDK，需要考虑
    - API要限流、限制次数、防止盗刷
    - 日志监控和数据上报

## 三、项目实践

### 1、项目需要实现的能力
- [x] 构建工具构建，配置开发环境、babel配置
- [x] 上传npm，支持导入 (可以不需要)

### 2、搭建基础架构，配置webpack。
```js
module.exports = {
    entry: {
        sdk: [path.resolve(__dirname, '../src/index.js')]
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    output: {
        path: path.resolve(__dirname, '../dist'),
        filename: '[name].js',
        library: 'SDK',
        libraryTarget: 'umd'
    },
    module: {
      rules: [
        {
          test: /\.ts?$/,
          exclude: /node_modules/,
          use: [
              {
                loader: 'babel-loader',
                options: {
                  presets: ['@babel/preset-env'],
                },
              },
              {
                loader: 'ts-loader',
                options: {
                  compilerOptions: {
                    noEmit: false,
                  },
                },
              },
            ],
        },
      ]
    }
```

### 3、实现SDK的接口

1、在调用之前，我们需要引用第三方库， 直接插入head中

```ts
export const scriptInit = (src: string, callback?: Function) => {
    const script:any = document.createElement('script'),
        fn = callback || function(){};
    script.type = 'text/javascript';
    //IE
    if(script.readyState){
        script.onreadystatechange = function(){
            if( script.readyState == 'loaded' || script.readyState == 'complete' ){
                script.onreadystatechange = null;
                fn();
            }
        };
    }else{
        //其他浏览器
        script.onload = function(){
            fn();
        };
    }
    script.src = src;
    document.getElementsByTagName('head')[0].appendChild(script);
}
```


2、在项目中使用

ES6 Modules导入

```js
const { DWSDK } = JS-SDK
const sdk = new DWSDK()
```
### 4、上传NPM

接着我们发布下npm，一个JS-SDK就完成了。

登陆npm仓库，没有的话去注册一个,[地址](https://www.npmjs.com/)
```
npm login
```
选择一个中意的SDK名字，查一下是否存在，这里我们起个名字`DW-JS-SDK`

执行`npm version patch && npm publish --registry=https://registry.npmjs.org`，然后就发布成功了。