文档中心 > 千牛

千牛插件离线化

更新时间：2017/04/21 访问次数：57974

千牛插件离线化解决方案
方案简介
开发工具使用
性能打点
回调签名
插件（离线包）版本管理
插件审核

千牛插件离线化解决方案

方案简介

千牛插件离线化方案是为了解决弱网下千牛插件资源和数据加载缓慢的问题，以改善千牛的用户体验。

此方案的核心是利用本地存储的离线资源代替从网络请求资源，减少插件对网络的依赖，从而提高插件的加载性能。同时插件在实现业务功能时配合数据的本地缓存可以一定程度上进一步的提升用户的体验。

用户使用插件的整体流程如下图所示：

千牛在启动插件之前，先下载或更新资源离线包（下载及更新策略这里不细说）
千牛本地更新插件以后，使用本地资源打开插件
业务数据优先加载本地，然后从远程刷新

我们期望插件的开发者离线化插件在设计初期就需要抛弃原有web开发的思路。离线化的插件完全是纯客户端端的实现方案，HTML+JS+CSS只是UI和业务层的解决方案而已，并不代表他和传统的web应用有什么关系。

我们期望HTML+JS+CSS只是运行在千牛客户端，用于向用户呈现操作界面和数据。

我们期望插件的开发思路和native的客户端保持一致。UI的渲染和呈现是在客户端进行，只有数据请求是依赖网络。

我们期望插件和native客户端在弱网甚至无网络的环境下有一样的体验。UI界面优先展现本地数据，数据的更新策略可以有很多方式，比如用户主动触发界面刷新。基于这样的方式即使是无网络的情况下插件的数据浏览功能应该是可以保障的。

我们提供的支持

离线包开发和调试环境

基于手机代理的PC开发环境，支持插件在PC上快速开发同时可以调试千牛移动端提供的能力。
提供离线包的发布工具，方便离线插件发布到移动千牛的H5容器进行测试。

插件性能分析工具

提供实时查看离线包资源命中率的功能
提供插件页面性能分析工具

离线包发布控制台

提供离线包测试、灰度、发布上线功能
提供版本检测和自助修复功能

开发工具使用

参考文档：https://www.npmjs.com/package/qianniu-cli

性能打点

插件的性能统计和分析需要ISV配合进行性能统计埋点才能得到结果。插件离线包的上线需要经过审核环境，只有通过审核的插件才可以进行灰度发布和正式发布。审核时会关注两点内容：1.插件的性能埋点代码添加的是否准确和合理。2.收集插件的页面性能作为基线数据。这个基线数据会用来监控线上自动采集的数据变化趋势，并且也是数据准确性监控的基线数据。下面简单介绍一下性能埋点代码的使用方法：

首先，需要更换新版的JS SDK，在网页中引入JSSDK文件，建议引用阿里cdn上的，如下：

使用性能打点API:

TOP.mobile.performance('home').ready('自定义标识');

TOP.mobile.performance('list').start('自定义标识');

TOP.mobile.performance('list').ready('自定义标识');

TOP.mobile.performance('detail').start('自定义标识');

TOP.mobile.performance('detail').ready('自定义标识');

API使用说明：打点功能只有两个TOP.mobile.performance('XXX').start('自定义标识')和TOP.mobile.performance('XXX').ready('自定义标识')。XXX部分有三个值，代表三个场景分别是：home（首页）list（列表）detail详情。

start方法打在触虚拟页打开的地方，比如点击列表的item里会打开详情页

就可以在点击事件的最后面加上TOP.mobile.performance('detail').start('自定义标识')。然后详情页数据渲染完成就可以加上 TOP.mobile.performance('detail').ready('自定义标识');。

首页比较特殊，首页不需要打start。因为H5容器知道Url加载的开始时刻。首页只要在数据加载完成（如果用了本地缓存，只要本地缓存加载完成即可）加上 TOP.mobile.performance('home').ready('自定义标识');就可以了。也就是说任何页面如果是重新URL加载的只要 TOP.mobile.performance('XXX').ready('自定义标识'); 就可以。请记住XXX改成对应的值就好了。

参考文档：http://sui.taobao.org/qn-sdk/mobile.html

回调签名

为了提高插件的安全性，插件的回调地址中增加了签名机制。离线插件获取签名后可以通知插件服务端进行校验。签名字段参数名“sign”具体签名算法如下：

public static String signTopRequest(TreeMap<String, String> sortedParams,
      String secret) throws Exception {
   // 第一步：把字典按Key的字母顺序排序,参数使用TreeMap已经完成排序
   Set<Entry<String, String>> paramSet = sortedParams.entrySet();

   // 第二步：把所有参数名和参数值串在一起
   StringBuilder query = new StringBuilder();
   query.append(secret);

   for (Entry<String, String> param : paramSet) {
      if (!TextUtils.isEmpty(param.getKey())
            && !TextUtils.isEmpty(param.getValue())) {
         query.append(param.getKey()).append(param.getValue());
      }
   }
   query.append(secret);
   // 第三步：使用MD5/HMAC加密
   byte[] bytes = md5(query.toString());

   // 第四步：把二进制转化为大写的十六进制
   return byte2hex(bytes);
}

插件（离线包）版本管理

1.概述

1.1 生命周期

每个插件版本的生命周期分为四个阶段，分别为：创建阶段、测试阶段、灰度阶段、发布阶段。

各个阶段的作用如下：

1）创建阶段

选择资源类型，上传版本的资源包，zip文件格式；

2）测试阶段

填写测试用户，版本只对测试用户可见；

3）灰度阶段

选择灰度比例、或者上传灰度用户名单，版本只对灰度用户可见；

4）全量发布

版本对全量用户可见。全量状态离线包对所有用户生效，失效时的处理办法同灰度离线包状态失效说明。

1.2 版本号

每个插件版本都具有一个版本号，采用点分十进制（0.0.1）形式，版本之间需要保持递增。

例如，某个插件版本的当前版本号为0.0.3，此时，如果要上传新的版本，那么，新版本号必须大于之前的版本号，可以使用0.0.4或者0.0.5等作为新的版本号。

1.3 离线包返回规则

1、用户千牛客户端版本在离线包版本限制范围内；

2、用户在测试名单、灰度名单，灰度比例中，或者有全量发布的离线包；

3、返回该插件所有离线包中，版本号最大的那个。

2 版本管理

2.1 新建版本

进入千牛开发控制台（https:// qnconsole.taobao.com），点击左侧菜单“版本管理-新建版本”，进入版本创建页面，创建新的插件版本。

1）QAP版本

对于QAP版本，只需要上传版本文件即可。

2）H5版本

对于H5版本，则需要手动填写版本号，以及支持的客户端版本范围。

2.2 测试阶段

处于“测试”阶段的版本只对测试用户可见。且可以直接失效，不影响除测试状态号其他用户。

填写用户昵称，昵称之间使用英文逗号“，”分隔。

2.3 灰度阶段

支持同时按照灰度名单、灰度比例进行灰度，用户只要符合其中任意一个条件，就会被命中。

其中：

灰度用户名单只支持txt文本文件格式，每行一个用户昵称。

灰度比例按照用户取模的计算方式，相同的比例一定会命中相同的用户。

。

2.4 全量发布

全量用户可见，并且不可以再继续编辑。

2.5 回滚

只可以回滚当前版本，版本回滚后，上一个正式版本将重新生效。

2.6 删除

处于“测试”、“灰度”状态的版本可以删除，已全量发布的版本可以选择“回滚”之后再进行删除。

发布说明：

建议严格按照发布步骤执行，先测试状态，没问题之后再按比例灰度，灰度没啥问题最后放全量，尽量避免全量发布之后失效操作，因为涉及到实时性，无法保证所有的用户能立马更新到最新版本。
当前最多同时存在两个非全量发布版本（测试或者灰度），此刻再提交新离线包会提示有多版本未发布，只要全量发布或者失效其中的灰度版本或者测试版本即可以再次提交。
新版本上传必须大于上一个版本，版本号自定义，格式遵循b.c，其中abc为数字，如1.0.0、0.0.3。其中版本号0.0.3比1.0.0版本号小。新版本上传最大支持5M；

插件审核

当前插件性能数据是否准确非常依赖于ISV打点位置正确与否，因此需要更严格的审核和校验机制

主要分为两部分：

首次灰度发布之前的离线包审核。当前离线包上线流程，测试à(离线包审核)à灰度à全量，只有审核通过之后才可以进入灰度发布。
线上性能数据校验。离线包打点之后，首次灰度审核以采集到基本的性能指标作为日后性能基准点，这部分将和实际线上数据对比，发现数据异常的情况将进行二次校验。

FAQ

关于此文档暂时还没有FAQ

有用(4) 我要提问

淘宝开放平台

千牛