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);
  })();

【PPT】那些年,我们一起跨过域

这个是入职腾讯第二月做的跨域分享,介绍了五种跨域方式,比较了他们之间的优缺点,希望可以解决小组内经常遇见的跨域问题。另外简单列举了另外五个跨域的方式,因为不经常用,所以也就简单的一笔带过了。

名字有点小清新,我想最后一个月的分享也是《那些年系列》:《那些年,我们一起跨过域》《那些年,我们错过的爱情(html5+css3)》,为什么是那些年呢,装清纯吧,感觉自己老了呗。

言归正传,我介绍的五种跨域方式是:

  1. document.domain
  2. location.hash
  3. window.name
  4. postMessage
  5. flash

以上五种跨域方式可能是现实工作中最常用的跨域方式,例如简单的跨域iframe自适应高度,你可以使用location.hash,跨子域可以使用document.domain,ppt每个方法都要详细的介绍,并且附上了我亲自写的demo哦~很有诚意是不(不要吐血),哈哈,好了又凑了一篇文章。另外附上昨天用css3画的企鹅:http://4.qdemo.sinaapp.com/qie.htm。ps:office 2010的ppt切换动画好炫哦

slideshare被墙,下载地址:http://4.qdemo.sinaapp.com/xdomain/naxieniankuayu.pptx


微盘下载:http://vdisk.weibo.com/s/6wt-O

IE中iframe和document.selection.createRange导致跨域

帮忙在活动中找bug,两层iframe,经过调试发现是document.selection.createRange导致的错误,在浏览器中报“拒绝访问”,猜测是跨域导致的。于是加上document.domain主域就搞定了。

本来以为是两层iframe导致的(因为他们反映一层iframe没有问题),于是自己建了个demo,test.qq.com/qq1.html代码如下:

<iframe src="http://demos.qq.com/qq2.html" frameborder="0" id="myIframe"></iframe>

demos.qq.com/qq2.html代码如下:

<script type="text/javascript">
    //document.domain = 'qq.com';
    var a = document.selection.createRange();
</script>

这样在IE9中访问test.qq.com/qq1.html就会报错,而把qq2.htmlqq1.html都添加document.domain='qq.com';就可以了。暂时原因不明了,记录在此备份下,懂得朋友可以来说道说道

使用html5 postMessage和window.name实现多浏览器跨域

跨域是个“很古老”的问题,因为浏览器的同源策略,导致不同域名下不能进行跨域名请求数据,虽然这样设计安全了很多,但是对于大型的网站同时维护多个域名就需要进行跨域操作。例如:微博开放平台的jssdk实现的跨域请求数据,再例如weibo.com和sina.com的同步登录。

之前我也说过不少跨域的方式了,有结合服务器端的,有纯粹javascript实现的跨域,例如:《利用跨域资源共享(CORS)实现ajax跨域调用》、《用document.domain+iframe实现Ajax跨子域》、《通过JSONP实现完美跨域》。在我的上一篇文章《javascript入门到高级PPT》中也提到了跨域。
当然也有不少关于跨域的文章,例如口碑UED的文章《跨域资源共享的10种方式》等等。大家可以去阅读一下。

今天我说的html5 postMessage和window.name也不是一种新的跨域方式,因为有不少人写文章写了,而实际应用的我不知道有哪些人?不过新浪微博的新旧两个jssdk都是采用这种方式,包括之前的人人网的xd.html,当然现在的人人和facebook都是通过flash实现的跨域,这不是今天说的内容。

html5 postMessage实现跨域

postMessage是html5的一个新功能,可以实现不同域名之间的通信,通过给postMessage方式发送数据,监听则通过在父子窗口添加onmessage事件进行。
缺点也就很明显了,只有支持html5的浏览器才支持这种跨域方式,像IE6、7当然就拒之门外了!

window.name实现跨域

window.name实现跨域也是一个比较老的问题,之前kejun写过一个demo,可是给的却是同域名的通信。
其实kejun的实例中就是实现跨域的,不过他采用了同一个域名,而且过程比较崎岖:

  1. 建立iframe,指定src为被跨域的页面
  2. 被跨域文件修改window.name,将数据传给window.name
  3. 将iframe.src修改为本域代理文件,然后就可以取到contentWindow.name
  4. 进行处理数据,清除iframe
    充分的运用了window.name因为页面的url改变而name不改变的特性。
    但是如果我们是自己用,还是可以的,而如果我们放出去要别人使用我们写的东西,那样学习成本太大。

多浏览器双向跨域

为了解决上面的问题,我们使用的方法就是如果支持postMessage的浏览器就使用postMessage,如果不支持的就采用window.name的方式,幸运的是在IE6、7中支持跨域设置window.name,而我们就可以简单的通过window.name来跨域。然后建立计时器来监听window.name是否发生了变化,如果变化则接收并分析window.name,然后做请求。