HybridStart混合应用开发框架

Posted 2020-09-25

转自我的博客，原文地址：http://refined-x.com/2017/06/26/%E5%9F%BA%E4%BA%8EAPICloud%E7%9A%84%E6%B7%B7%E5%90%88%E5%BA%94%E7%94%A8%E5%BC%80%E5%8F%91%E6%A1%86%E6%9E%B6/

HybridStart提供什么

开发模式

如果是跟我一样之前从未接触过APP开发的前端，我认为首先需要知道的是，APP不同于web的地方是需要很多初始化操作，比如判断是否已登录、数据预取、检查更新、注册推送、注册全局监听等等，经过这个过程后APP才能打开第一个页面，进入页面的生命周期。

APICloud里有一个非常重要但官方没怎么强调的概念叫根页面（root），就是APP启动后第一个打开的那个页面，这个页面非常特殊，相当于其他所有页面的父页面，它被关闭了意味着APP退出，他无法被其他页面调用关闭方法关闭，它是到达其他页面的必经之路。综合这些特征，这个页面非常适合用来做APP初始化，初始化完成后再立即切换到首页或者登录页，这时用户看到了第一个页面，但实际上是APP打开的第二个页面。

APP启动后root页就常驻后台，对于安卓机还需要在可能返回到root页的页面上做返回键拦截，提示退出APP而不允许返回到root，因为root是个只有js代码的空白页。那么混合应用的页面生命周期就应该是：

root -> index(exit) <=> page <=> page ...

 

开发中我们第一个要实现的就是root页的初始化功能，比如检查登录状态，然后决定是跳转到登录页还是主页，然后再去实现登录页 or 主页。

APP的数据交互几乎全部依靠后端接口，因此很有必要事先约定一个交互格式，方便统一做异常处理。比如最简单的先把json的大结构定下来，起码状态、数据、提示信息字段都得有，对于列表数据还需要一个信息总数字段，这样下来一个基本的交互格式就像这样：

{
    "status": "Y",      //请求的状态 "Y"/"N"，也可以根据情况扩展其他
    "data": [{...}],    //请求的数据 数组或对象
    "msg": "",          //【可选】服务端提示信息
    "count": [number]   //【可选】当获取列表数据时，需附加count数据指明列表总数，用于前端分页
}

 

这样我们就可以封装一个数据请求方法，在方法里对某些情况做自动处理，比如当发现status不是"Y"的时候就自动提示msg字段的信息，就不用在每一个业务逻辑里写错误处理了。

代码组织

稍微复杂点的APP有个几十近百的页面很正常，所以APP代码组织首先要解决的是页面组织。

页面肯定得放在一起管理，但又不能直接罗列在一起，那就先建一个view/文件夹，然后按功能模块分二级文件夹，把会员相关页面都放进member/，商品页面都放进product/……；页面的脚本和样式也不希望内联，最好每个页面对应模板、样式、脚本三个文件，那就将他们三个也装进文件夹，以页面名称命名。这样页面文件就形成了channel-page-pagefile的结构，目录就变成了这样：

view/
 |--- member/               //会员栏目
 |      |--- info/              //会员信息页
 |      |        |--- temp.html
 |      |        |--- style.css
 |      |        `--- script.js
 |      `--- set/               //会员设置页
 |              |--- temp.html
 |              |--- style.css
 |              `--- script.js
 |      
 |--- home/                 //APP首页
 |      |--- temp.html
 |      |--- style.css
 |      `--- script.js
 ...

 

这样即使有再多的页面，找起来也有迹可循，不至于在文件堆里看花了眼，将页面样式和脚本拆分出来也是为了开发方便，因为页面代码一旦很长，上上下下的巴拉css和js也挺痛苦的，不如拆开干净利索，反正都是本地文件，几乎没什么加载问题，将页面用文件夹的形式管理还有一个好处，就是可以将页面的独有资源放在各自文件夹内管理，比如图片就不需要全部丢进公用文件夹了，将来打开一看一大堆图片，都分不清哪个有用哪个没用。

然后是脚本组织，APP开发需要写大量的js，组织js的目的就是层层过滤，将非业务代码过滤出去，使注意力可以更多的放在业务脚本的开发上。

首先我们肯定要将类库剥离出来，在类库和业务之间再划分出插件、服务、公用脚本。

公用脚本就是类似返回按钮的监听、图片点击的监听、兼容性处理等，每个页面都得引用它（除了root），可以把他们都抽到common.js里，方便统一修改；还有一些业务上常用的方法，比如格式化、查坐标等等，不是每个页面都能用到，但也很有必要集中在一起管理，暂且就叫他server.js；另外还有一些插件类的脚本，比如上传、表单验证，这种就分别封装成模块，一起放进modules/文件夹；最后是类库，也是框架的核心，我们称之为core.js，这里面放的是常用类库以及对引擎接口做二次封装，二次封装至少有三个好处，一是可以精简api，如果看过APICloud的文档感觉还好的话，建议去看一下Appcan的文档，那醉人的api设计，简直欲仙欲死；二是底层引擎的api假如更新了，不需要修改业务代码，只改core.js中对应的封装就好了；三是便于更换底层，实际上这个框架的雏形就是基于Appcan实现的，后来弃坑转到APICloud无非就是换了一套底层api，框架自身api没有大的改动。

最后剩下的就是散落在各个页面里的script.js了，那么最终的脚本组织是这样的：

|--- sdk/
|       |--- modules/
|       |      |--- upload.js
|       |      |--- ...
|       |--- core.js
|       |--- server.js
|       `--- common.js
|--- view/
|       |--- page/
|       |       |--- script.js
|       |--- ...

 

css以及其他静态资源的组织就很简单了，没必要细讲，再上一个完整的目录结构吧：

  |-- docs/                 //文档(不需要上传打包平台)
  |-- error/                //app错误页
  |-- res/                  //app静态资源(图片、模板等)
  |-- sdk/ 
  |    |-- modules/             //插件模块
  |    |-- font/                //字体图标
  |    |-- core.js              //核心库
  |    |-- server.js            //业务方法
  |    |-- common.js            //页面公用代码
  |    `-- ui.css               //公共样式
  |-- view/                 //app页面
  |-- config.js             //框架配置
  `-- config.xml            //APICloud配置

 

技术栈

js分的这么零碎肯定离不开模块化，因此整个项目是基于seajs实现的模块化加载；DOM操作用的jQuery 2.x，很多人觉得做混合应用还上jQuery太low，我要说多webview模式让混合应用真的很像一个网站，DOM操作少不了，当然你大可换成zepto或自己封装几个方法去用，我觉得差别不见得有多大，都是本地资源差个几KB有区别吗；模板引擎用的etpl，这个很有用，大量的异步数据渲染，没有模板引擎不行。

类库都是直接将压缩后的代码放进core.js顶部，理论上可以随意增删改，但上述三个类库在其后的app对象实现中也有应用，因此不能直接删掉。除这三个以外的类库如果不需要可以删，比如xss.js，一个防御跨站脚本攻击的库。

HybridStart的意义

目的及原则

我有一点代码洁癖，体现在我不喜欢任何二次封装的东西，我希望通过最短的路径去触及功能实现的关键，所以抱着这样的目的，最开始我连官方的js SDK也不用，直接调用引擎api开发业务，我认为这是最快、性能最高的方式。

然而事实是，引擎提供的api效率真心不高，而且可靠性堪忧，当年用Appcan开发第一个项目的时候，简直难受的想死，bug多到"举步维艰"你能想象吗，转到APICloud后虽然没有这么多明显的bug了，但部分api偶发性失灵还是有的，这种问题基本就没办法了，后来看了一些对混合应用实现原理的介绍才知道，这玩意本来就是个hack，反射弧就是比较长，体验上"不利索"啊，偶发性的失灵啊，也就可以理解了，其实难怪，要真能像调用原生一样快那还要原生干什么。

所以后来我改变了思路，不能再面向引擎编程了，因为你不知道一个api背后是怎样实现的，就不知道这个api的真实使用成本，所以我开始接受二次封装，并且原则上尽量少的使用引擎能力。

一开始是修改官方的js SDK，将无用的功能删掉，将需要的功能加上，改着改着发现这个js SDK跟我的需求差别太大，干脆就重写了一个，该有的有，该扩的扩，用起来很爽。随着开发的深入，越来越发现其实利用有限的几个api就可以实现绝大多数需求，如果仔细研究引擎的api，会发现真有些功能是非必需的，或者说是语法糖，怎么说呢，感觉就是api"设计的不优雅"。甚至有的功能实现还不如js模拟来的效果好，背后的开发质量可见一斑。

在这样的目的和原则下，引擎api被二次封装进了app对象，除了常用核心方法被直接挂载在app上之外，还包括了app.crypto、app.ls、app.window、app.ajax几个模块。

app.openView

app对象里封装了所有混合应用开发需要的功能，但是很多琐碎的功能实现都尽量的被隐藏起来了，可能开发中只需要修改一个配置就能使用，目的就是为了简化开发。这里我们就说一下app.openView()这个方法，这个方法用来打开一个页面，可以说是开发中最常用的方法，借此也让大家对HybridStart到底做了什么有一个感性的认识。

首先我们看引擎本来提供的api是什么样的：

api.openWin({
    name: ‘page1‘,          //为窗口命名，方便调用关闭方法将其关闭
    url: ‘./page1.html‘,    //页面路径
    pageParam: {            //参数
        name: ‘test‘
    },
    animation: ‘push‘,      //动画效果
    subType: ‘form_right‘   //动画方向
});

 

这个方法的配置项还有很多，列出来的是开发中最常用到的几个，即便只是这几个配置每次写也已经够罗嗦了，app.openView()可以说就是对这个api 的封装，希望通过各种方式在不牺牲功能的前提下简化配置，那我们就从这几个配置入手，挨个来看怎么简化。

name属性用来为一个窗口命名，这个名称将来可以用于调用某些方法对其进行操作。我们要省掉这个配置就只能自动生成，但这个名称日后还有用，所以不能随机生成，必须有一定的规律，这里可以结合页面组织来解决，按照我们前面讲的规则组织后页面分为两种，一级页面"/view/channel/temp.html"和二级页面"/view/channel/page/temp.html"，规律还是很明显的，只要提供页面所属的channel名称以及如果是二级页面的话再加上page名称，就可以定位到这个页面，并且通过channel + "_" + page来得到一个唯一的name值。那我们就先假定openView方法需要channel和page两个参数，page是可选的，调用时将是这样：

app.openView(‘home‘);           //url: "/view/home/temp.html", name: "home"

app.openView(‘member‘,‘set‘);   //url: "/view/member/set/temp.html", name: "member_set"

 

还不错，name和url都解决了，属性pageParam的处理相对复杂，我们放在后面说，先来看animation和subType。

这两个属性是最应该被封装掉的，页面切换的动画类型肯定要集中到一个全局配置中管理，调用时animation可以省掉；动画方向配置基本上就是个伪需求，打开自然就是右推，关闭自然就是左推，分别封装进打开和关闭页面方法里就好了，subType也可以省掉。

现在来看pageParam，用来给页面传参，参数格式是Object。好，这个需求必须有，我们要让app.openView()支持传参，语法将变成这个样子：

app.openView(param[Object], channel[String], page[String]);

因为page是可选的，放在最后便于实现，因此将param参数放到前面。好像看上去也还行，但肯定还会有其他配置，不能一再的往上加参数吧，怎么办。

这里有一条经验，页面传参多数发生在从列表页打开详细页的时候，这时我们传的参数是一个id，也就是一个字符串，实际上绝大多数情况下的页面传参都只是一个字符串，需要Object的情况不多，基于这个前提，我们将param参数扩展一下，既可以接受字符串也可以接受对象，当接受字符串时将该值作为参数传递给新页面，当是对象时允许该对象包含对openView方法的所有配置，当然其中也包括了页面参数，说起来有点绕，看代码：

app.openView(‘newsID‘, ‘news‘, ‘detail‘);           //实际开发中最常用的字符串传参

app.openView(null, ‘home‘);                         //如果不需要传参，抱歉必须传一个null/undefined占位

app.openView({                                      //Object类型的参数得这么传
    param: Object
}, ‘home‘);  

app.openView({                                      //这里还可以配置openView方法的其他参数
    duration: 350
}, ‘home‘);

 

这样所有的问题都解决了，但有一个小瑕疵，就是没有参数必须传null/undefined占位，因为page参数已经是可省的了，param参数实在没办法再做判断，不过这个null/undefined传的也不是一点意义没有，这里又得说来话长了。

前面说过给页面传参有两种方法，一种是通过api提供的pageParam，另一种是通过localStorage跨页面存取值，pageParam的问题是新页面取值比较慢，取值代码可能是这样的：

//原生功能就绪回调
app.ready(function(){
    var pageParam = api.pageParam; 
    //基于pageParam的后续操作，比如页面渲染、表单验证，事件绑定
    ...
});

 

app.ready()是框架封装的原生功能就绪回调，这是一个异步回调，通常，为了提高脚本响应速度我们会把不需要原生能力的操作放在app.ready()之外，使其同步执行，问题在于，如果基于页面参数的后续操作恰好是不需要原生能力的，但为了等待取参数，也必须被放进app.ready()内执行，这就很不爽了。

所以框架提倡的传参方式是用localStorage，在新页面可以同步取值，这种方式唯一的问题是可能造成资源浪费，各种参数放进本地，怎么清理？我的方法是约定一个专门用来传参的键crossParam，每次传参都写进这里，反复擦写最终留下的只是最后一次的参数值，app.openView()已经对此做了封装，参数将自动存进localStorage.crossParam，参数如果是对象类型将做JSON.stringfiy()处理，因此如果传的是对象，取值后需要自己做JSON.parse()处理。

//同步取得页面参数
var param = app.ls(‘crossParam‘);       
//执行不需要原生能力的操作
...

app.ready(function(){
    //执行需要原生能力的操作
    ...
})

 

回到app.openView()方法第一个参数必须占位的问题，他的意义在于，当app.openView()检测到null/undefined时会将本地存储中的crossParam键删掉，将造成浪费的可能性降至最低。

当然，官方的pageParam方式也没有废弃，如果传递的参数是对象的话，pageParam和localStorage两种方式都生效，可以通过api.pageParam 的方式也可以取到值。

经过这些封装，打开页面的语法已经非常简单了，但app.openView()还有很多其他功能，比如以弹窗形式打开页面、以带标题栏的形式打开页面、打开新页面同时关闭当前页面、或者打开一个网页，这些功能的实现都相对复杂，就不一一展开了，这里只着重介绍封装思路，如果有兴趣可以去HybridStart 文档看一看。

后记

吹了半天，还得回到选型上来，我并不觉得多数项目适合这种方案，我甚至觉得只有少数项目，或者只有项目的起步时期，可以用这种方案快速上马快速迭代，我理想中的混合应用形态是原生为主web为辅的，但从一个前端的角度看，我并没有发现更好的可行性方案，有人可能会说React Native，但那个东西还是需要原生开发基础的好吗，而且如果APICloud在UI组件方面再进一步，貌似也可以接近React Native的效果。

总之，如果你觉得自己的项目正好适合这个方案的话，这个框架可能对你有帮助。

源码： Github

源码本身也是一个示例项目，上传平台即可编译。