【quickhybrid】API规划

前言

当一切就绪后，就要开始进行API规划，这一块是整个Hybrid框架中很是重要的内容，毕竟对于前端页面来讲，只会经过JS API来调用功能。
基本上，API调用起来是否方便简洁影响着整个体验。

这里将内容细分为如下几点：

• API约束（包括调用格式，传参格式，回调格式）
• 功能规划（约定这个框架应该提供什么样的功能）
• 权限校验（很重要的一块，校验后才能调用，包括权限校验的代码格式，校验一些什么内容，以及哪些API无需校验）
• 模块化的API（按照模块划分，每个模块能够做为单独的组件，便于拓展）
• 其它优化（如在PC端调试API的页面，部分API支持Promise等）

API约束

API调用关乎着整个体验，咱们约定全部API统一采用以下调用方式

quick.模块名.方法({
    参数1: "",
    参数2: "",
    success: fucntion(result) {
        // 成功回调
    },
    error: fucntion(error) {
        // 失败回调
    }
});

约束说明

• 全部接口都为异步调用
• 接收一个object类型的参数

• 成功回调success

  • 经过result获取成功数据
  • 回调函数的触发时机由具体的API决定，有的API是调用时便可回调（短时间），有的是某个事件触发后才被回调（长期）
• 失败回调error，全部的API调用错误都会走失败回调

功能规划

混合开发框架最重要的一个功能就是__将原生功能以JS API形式提供给前端页面调用__

本框架的API规划以下：（这个项目中仅规划了部分功能，实际使用中自行拓展便可）

quick
    |- ui               // 系统ui组件
    |   |- toast        
    |   |- alert       
    |   |- confirm       
    |   |- prompt          
    |   |- showWaiting         
    |   |- closeWaiting          
    |   |- actionSheet       
    |   |- pickDate     
    |   |- pickTime
    |   |- pickDateTime
    |   |- popWindow
    |- page             // 页面（webview）管理
    |   |- open
    |   |- openLocal
    |   |- close
    |   |- reload
    |- navigator        // 导航栏控制
    |   |- setTitle
    |   |- setMultiTitle
    |   |- hookSysBack
    |   |- hookBackBtn
    |   |- setRightBtn
    |   |- setLeftBtn
    |   |- setRightMenu
    |- auth             // 权限认证相关
    |   |- getToken
    |- device           // 设备相关
    |   |- setOrientation
    |   |- getDeviceId
    |   |- getNetWorkInfo
    |   |- getVendorInfo
    |   |- closeInputKeyboard
    |   |- vibrate
    |   |- callPhone
    |   |- sendMsg
    |- runtime          // 运行环境
    |   |- launchApp
    |   |- getAppVersion
    |   |- getQuickVersion
    |   |- getGeolocation
    |   |- clearCache
    |   |- clipboard
    |   |- openUrl
    |- util             // 其它工具
    |   |- scan
    |   |- selectImage
    |   |- cameraImage
    |   |- selectFile
    |   |- openFile

上述规划的是最经常使用到的功能，具体每个API的介绍，传入参数传出参数等会在框架的API文档中提到

权限校验

若是整套框架要对外开放（如容许第三方按规范接入），那么权限认证是必不可少的！

若是没有权限认证？能够想象下，随便一个页面就能调用任意API，获取敏感信息。。。

那么权限认证应该是怎样的呢？根据不一样需求，能够划分一个等级。

• 平台级别的（像钉钉、微信这类对外开放的），须要配合后台，有完整的受权，签名，校验机制
• 项目级别的（N个项目同一个框架，但业务各不相同），简单的应用内部配置，直接校验一些域名白名单信息便可

固然了，这个框架是后面的项目级别的，大批量的项目都采用的，所以直接简单配置便可（示例中是在原生预留了这个入口，但没有实现）

这里暂不谈具体实现（实现可参考源码），只说说权限认证的流程：（如钉钉、微信中的）

quick.error(function(error) {
    // 处理错误
});

quick.config({
    ...
});
quick.ready(function() {
    // TODO: 处理验证成功后的事情，例如调用api
});

能够看到，和其它框架同样，前端也是config，ready，error三步，
而后原生接收到config时，内部进行校验（校验内容能够是检测页面地址是否符合域名白名单等等...）

并且，若是config失败或者没有校验，那么敏感API都没法调用

无需校验就可用的API

并非全部API都需校验后才能用，咱们约定如下API默认就可用（这里是一个粗糙的划分，实际上能够精确到每个API）

ui模块的全部API
page模块的全部API
navigator模块的全部API

这样作的好处是，若是不涉及到一些敏感数据，能够无需校验，提供效率（校验若是规则毕竟重的话对速度仍是有影响的）

模块化的API

有一个全局变量quick，但API并非直接绑定在全局变量下，而是按模块划分，譬如

quick.ui
quick.device
quick.page
...

这里说明一下，用模块化划分，除了前端调用会更清晰外，原生进行API定义与组件API拓展时也更方便。

组件API的拓展机制

关于组件API的拓展机制，这里也不具体描述如何实现（实现可参考源码），仅说说大概是一个什么样的东西。

默认状况下，框架会注册如下组件（前面已经规划的全部模块）

ui
page
navigator
auth
device
runtime
util

可是假设某项目中忽然遇到了一个需求，要新增一个支付功能，而且要以API的形式提供给H5页面调用，该如何实现呢？

注意，这个框架设计的初衷是能够供N个项目使用，因此不可能全部的功能都集成进入框架中的，各个项目能够拓展本身的组件

这时候就须要规划这个拓展机制了，以下

// 1.前端config时，传入须要注册的组件别名
quick.config({
   jsApiList: ['pay', 'speech']
});

// 2.原生框架中，接收到config后，基于传入的别名，去对应项目配置文件中查询路径，而后将对应路径的API实现类注册
// 对应的组件的API实现类不是放框架中的，而是由各自的项目管理的，到时候框架就是一个固定的库，给各个项目引用
// 代码实现这里省略
...

// 3.前端中，经过一个固定的方法，调用刚注册的组件API中的功能
quick.callApi({
    name: 'xxx',
    mudule: 'pay',
    ...
    data: {},
    success: function(result) {},
    error: function(error) {},
});

经过这一套机制，能够保持框架的可拓展性，就算应用不一样的项目中，N多的功能，也能经过这种方法拓展，保持一致的使用

其它优化

在大致功能都实现后，接下来还须要作一些优化功能，具体效果能够是简化调用，也能够是方便调试

部分API支持Promise

前面定义的API中都是基于普通的回调进行的，在多层回调嵌套时仍然会毕竟麻烦，所以能够拓展支持Promise调用方式

在拓展前，先定一个基调：__全部短时间回调都支持Promise调用，长期回调不建议使用Promise__

由于长期回调涉及到屡次回调（好比右上角按钮），因此不建议使用Promise，若是强行要使用，这些API调用完毕后立刻就会进入then

具体实现参考源码，这里稍微对比下普通调用与Promise调用

quick.ui.alert({
    title: '提示',
    message: 'sd#ddd测试',
    success: function(result) {
        console.log('点击alert成功');
    },
    error: function(error) {
        console.error('失败:' + JSON.stringify(error));
    }
});

quick.ui.alert({
    title: '提示',
    message: 'sd#ddd测试',
}).then(function(result) {
    console.log('点击alert成功');
}).catch(function(error) {
    console.error('失败:' + JSON.stringify(error));
});

上述还只是没有嵌套的对比状况，有嵌套时，区别更大

PC端调试API

相似于钉钉的调试页面，这里也规划了一个在PC端调试API的页面（基于websocket），后续会有更详细的说明。

原理方面的源码能够先参考https://github.com/dailc/node-server-examples/tree/master/node-socketio-hybriddebug

能够先预览下效果

其它

其它优化后续再介绍

返回根目录

• 【quickhybrid】如何实现一个Hybrid框架

源码

github上这个框架的实现

quickhybrid/quickhybrid