qianniu-cli

写在前面

千牛离线插件方案的实施效果，不在于开发工具提供了哪些方面的支持，此方案是否有成效的关键在于开发观念的改变和技术方案的实施。

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

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

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

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

Getting Started

qianniu-cli工具是千牛离线插件的开发工具。其中包括了项目创建、调试、发布等功能

1. 环境搭建

所谓“工欲善其事，必先利其器”，搭建好方便的开发环境是完成插件开发的基础。qianniu-cli是进行千牛离线插件开发的辅助工具基于node.js开发，所以开发环境必须安装node.js

1. 安装node.js

• 访问https://nodejs.org/点击“Install”

• 下载安装包

• 下载完成以后完成安装

• 测试安装结果

  $ node -v
  v0.12.0
  

2. 安装qianniu-cli

• 使用npm直接安装（推荐）

  $ npm install qianniu-cli -g
  

• 测试安装结果

  $ qn --help
  Usage: qn [options] [command]
  Commands:
    create <projectName>  create a Qianniu plugin project
    debug                 debug Qianniu plugin project
  Options:
    -h, --help  output usage information
  

2. 开始插件开发

1. 网络环境要求

• 手机和PC/MAC在同一网段
• PC防火墙放开对8800、8808端口的限制

2. 创建新项目

qn create helloworld

在当前路径创建了一个新的"helloworld"项目，在“helloworld”目录下

3. 项目结构

- helloworld/    #项目根目录
	+js/
	+css/
	+image/
	+html/
	-index.html
	    

4. 开发调试

离线包开发支持两种开发和调试方式：

• 在PC上开发，在依赖chrome等开发者工具进行前端的调试，这里会有一个问题——千牛native能力在PC上怎么联调？这个问题下面会得到解答。

• 在PC上完成代码开发，然后将插件发布到千牛移动端，然后依赖chrome的远程调试功能进行调试（仅支持千牛Android客户端）

下面先介绍一下第一种方案，这个方案同时支持千牛Android客户端和千牛iOS客户端，这个方案的优点是可以节省调试和开发的时间，提高开发效率。第二种方式更推荐进行真机回归时使用。

• 使用以下命令开启调试功能

   cd helloworld
   qn debug
   		    
  

  此命令运行以后会启动一个websocket服务为了给PC上的插件页面提供手机的native能力。千牛客户端和PC界面会通过websocket通道进行通讯。与此同时你会发现PC浏览器默认被打开页面

  http://127.0.0.1:8800/console

   proxy:		#显示移动客户端和代理服务器的连接信息
   connect:    #显示插件界面和代理服务器的连接信息
  

• 将移动端连接到代理服务器

  Android登陆手机千牛->点击“我的”->点击“设置”->点击“关于千牛”->连续点击千牛Logo支持切换到debug模式->选择“插件调试”->输入相应信息点击"确定"，打开移动端代理界面->点击“提供代理”

  iOS登陆手机千牛->点击调试版本右上角状态栏的红色按钮->点击“启动调试插件”->输入相应信息点击"确定"，打开移动端代理界面->点击“提供代理”

  注：代理服务器IP——运行qn debug命令的机器IP，需要能被移动端访问；代理服务器端口——默认8800

  此刻在刷新这个连接

  http://127.0.0.1:8800/console

  你会发现信息发生了变化

   proxy:
   88684537 from ::ffff:10.2.15.157 #显示有个移动端代理连接成功
   connect:
  

• 打开插件开始开发和调试

  打开插件的默认首页

  http://127.0.0.1:8808/index.html

  注意：8808端口号

• 创建一个可调试的H5页面

  千牛离线包中的H5界面采用标准的HTML5协议，没有额外的裁剪和修改，所有H5能力的支持程度依赖于不同的手机版本。

  如果希望新建的H5界面可以通过上述方式进行调试，唯一要求：在HTML文件</body>标签前添加以下js依赖

  <script type="text/javascript" src="./js/sdk-mobile-debug.js"></script>

5. 移动端回归测试

• 打离线包

   cd helloworld
   qn package www.test.com:8080
   
  

  注：qn package <host> 命令host参数可以包含端口号，host参数的目的是生成zip文件的根路径名称，因为移动千牛客户端是将url映射到本地路径来查找离线文件，所以离线文件的更路径应该是插件回调地址的域名

  此命令正常运行完成以后会有类似的输出结果，提示离线插件压缩包的存放路径以及压缩包的大小。

  /your_path/hello_output/www.test.com_8080.zip:1512 total bytes

• 安装到千牛移动端进行测试

  • 先使用命令生成安装二维码，二维码的作用是方便开发环境上的zip包安装到移动千牛里。

    qn test 2123456 1.0 /your_path/hello_output/www.test.com_8080.zip

    qn test <appKey> <version> <packagePath>

    参数说明：

    appKey插件appkey；

    version资源包版本号；

    packagePath资源包存储路径，此路径由qn package <host>执行完成后输出

  • 上面的命令会自动打开浏览器，请在浏览器中输入开发环境的ip地址，然后点击生成二维码

  • 打开千牛使用首页上的“扫一扫”功能对二维码进行扫描，离线包会千牛后台被下载安装

  • 打开你的插件进行测试

3. 命令

• 创建插件项目

   qn create <projectName>
   
  

• PC端启动调试插件功能

   qn debug
  

  注意：必须进入插件项目的根目录执行此命令

• 打出离线插件包

   qn package <host>
   
  

  注意：命令host参数可以包含端口号，host参数的目的是生成zip文件的根路径名称，因为移动千牛客户端是将url映射到本地路径来查找离线文件，所以离线文件的更路径应该是插件回调地址的域名

• 发布到移动端进行回归测试

   qn test <appKey> <version> <packagePath>  create test qrCode
  

  参数说明：appKey插件appkey；version资源包版本号；packagePath资源包存储路径，此路径由qn package <host>执行完成后输出

• 查看帮助说明

   qn --help
  

4. 离线包命中规则

• 离线包入口请求URL是什么？

  离线包安装后，没有访问离线包的入口URL。千牛访问插件的时候仍然使用插件回调地址打开插件，是否命中离线包，是通过URL和离线包中的文件路径进行匹配后决定的。

• URL和离线包的匹配规则是什么？

  例如千牛的H5容器中访问插件的一个页面路径为：http://123.abc.com/xx/yy/zz.html。使用离线包策略时。千牛会查找对应插件的123.abc.com.zip这个压缩包内的文件。

  映射规则：

   http://123.abc.com/xx/yy/zz.html >> 123.abc.com/xx/yy/zz.html
   https://123.abc.com/xx/yy/zz.html >> 123.abc.com/xx/yy/zz.html
   http://123.abc.com:8080/xx/yy/zz.html >> 123.abc.com_8080/xx/yy/zz.html
   https://123.abc.com:8080/xx/yy/zz.html >> 123.abc.com_8080/xx/yy/zz.html
  

5. 插件的日常维护和问题排查

• 使用qn log 命令来和客户端建立连接输出相关的日志

   qn log
   
  

  你可以看到如下的信息

   这是我的ip地址：192.168.0.102
   请在 ios千牛的debug客户端-设置日志输出-ip地址栏中输入192.168.0.102，点击连接即可。
   tcp listening at 8786
   
  

• 下载最新的千牛移动客户端debugger版本，ios在3.8.3以上，android暂时还未支持，按照上述提示操作即可。

js bridge API

原有千牛js bridge api使用开发者账号进入登陆千牛查看插件文档即可

• 新增开放的通用协议文档

  • 商品列表

  • 选择商品

  • 商品详情

  • 交易列表

  • 交易详情

  • 退款详情

  • 交易选择

  • 发送优惠劵

  • 商品审核详情

  • 商品体检日报

  • 供销商品详情

  • 打开消息/服务号名片

  • 打开消息/服务号消息列表

  • 打开旺旺聊天窗

  • 打开网址

  • 打开牛吧活动详情

  • 打开工作台设置

  • 打开子账号设置

  • 打开反馈组件

  • 打开轻任务列表

  • 打开轻任务详情

  • 创建轻任务

  • 打开分享组件

  • 打开淘宝大学课程列表

  • 选择文件

  • 预览文件

  • 地理位置

  • 打开插件服务详情

  • 获取文件数据

  • 获取文件信息

  • 裁剪图片

  • 压缩图片

  • 添加日程安排

  • 生成二维码

  • 手机截屏

  • 打开商品选择组件

  • 打开店铺名片

  • 优惠券列表

开发流程

常见问题

• windows上安装qianniu-cli后提示，提示“‘qn’不是内部或外部命令”怎么解决？

  主要原因是node.js或者npm的安装路径存在空格。参考这个解决方案：http://www.cppblog.com/jinq0123/archive/2015/01/31/209688.html/

• 为什么没有命中离线包里的资源？

  参考前面介绍的离线包命中规则

• 如何测试升级后的插件性能？

  Android登陆手机千牛->点击“我的”->点击“设置”->点击“关于千牛”->连续点击千牛Logo支持切换到debug模式->点击“显示H5性能”

  对于小米手机请到“安全中心”找到千牛应用，然后允许千牛显示悬浮窗口。