JavaScript sdk(jssdk)设计指南

今天看到一篇《javascript sdk设计指南》，内容篇幅比较多，很多实际是问题的枚举，但是信息量太大，所以我结合之前做微博开放平台和运营活动平台的经验，说下jssdk的设计和一些核心问题的解决方案。

一个jssdk一般是指提供给第三方人员使用的一段js，通过这个js实现一些平台化产品提供的服务，比如微博的jssdk。整个jssdk的设计有一下几个核心问题：

  • 代码如何被使用页面接入
  • 如何实现跨域通信
  • 如何实现优雅api的设计
  • 公共资源的使用
  • 代码组件化

先说第一个问题

代码如何被使用页面接入

这个问题涉及到几个小问题需要讨论：

  • 命名空间
  • 样式冲突
  • 版本维护
  • appid等参数的传入

命名空间

在「命名空间」部分，需要做到不污染环境，保护好自己，即不要对本来的页面造成命名的破坏，只是用一个命名空间，又要考虑到第三方页面的复杂性，防止跟错综复杂的命名空间冲突。

要做到这点，需要我们在命名空间命名的时候多注意下，尽量不要使用业内通用的命名方法，比如驼峰，名字尽量起的怪一些，偏一些，一般，要么使用_开头（甚至多个），要么使用项目代号这些不太被别人想到的名字，嗯，我记得有人命名空间用av，很好呀！

还有一种方式是动态的命名空间，在url中带上namespace=xxx，本节结束后面会统一给出示例

样式冲突

除了js命名空间问题，如果jssdk带有UI组件，那么还需要考虑css的样式冲突问题，这里不用多说，记住以下几点：

  • 一些复杂的widget可以使用iframe方式引入
  • 不使用id
  • 使用带前缀的class命名，前面用一个class最好包裹
  • 自己做reset！
  • 跟js相关的class要有特殊的约定（比如_J-xxx ）或者使用data-id代替

其实利用sass、less这些预编译语言很容易

例如下面的代码：

$name: avUI;

.#{$name}__dialog{
    @include reset();
    .#{$name}__dialog__header{
        color: white;
    }
}

版本维护

版本维护的目的是保证代码最新，功能最全，而不用每次做了升级，通知所有使用的第三方开发者把自己页面的代码挨个更换。所以这里版本维护不应该暴漏给使用者，比如在url使用版本号，到了2.0版本，通知使用方替换，这是不合理的，总有些公司或者人不配合的。最好的方法是设计的时候就要考虑到这个问题。

一般有两种比较好的方式：

  • 小拖大，动拖静：即第三方引入的js是一个动态的，或者没有缓存没有cdn的，然后由它带出后面的cdn
  • 隔段时间动态创建script

推荐使用「小拖大，动拖静」，后面介绍组件化也要使用这个方式来按需加载代码

小拖大，动拖静

核心代码示例

(function(){
    .....
    var url = '最新版本cdn的地址';
    load(url);
}())

隔段时间动态创建script

代码示例：

(function () {
    var s = document.createElement('script');
    s.type = 'text/javascript';
    var t = +new Date;
    t -= %864E5;
    s.src = 'http://xxx.com/sdk.js?t='+t;
    var x = document.getElementsByTagName('script')[0];
    x.parentNode.insertBefore(s, x);
  })();
前端开发

more >>