YYFJS
YYFJS@BETA
YYF前端请求和数据接口封装JS库。
The frontend JavaScript library for YYF RESTful API request.
2.x为Beta版，安装方式
npm i yyfjs@beta -S
在线演示示例：
Install
1.1 安装方式
- with
<script>(直接引入) :<script src="http://unpkg.com/yyfjs"></script> - with npm(使用npm 包安装) :
npm i yyfjs -S - with bower(使用bower安装) :
bower i yyfjs -S
1.2 Minimal usage(示例)
- gh-pages 分支稳定版和最新开发版
- 也可以在unpkg.com/yyfjs/下载最新版发布版代码
1.2.1 In Browser(浏览器中直接使用)
<html>
<head>
<script src="http://unpkg.com/yyfjs"></script>
</head>
<body>
<script>
YYF.get('Index/test').success(console.log);
</script>
</body>
</html>
1.2.2 Using package (包管理方式）
var YYF=require('yyfjs');
YYF.get('Index/test').success(console.log);
Interface
方法接口和API
2.1 Examples
- 快速定义
//设置请求root路径
YYF('https;//yyf.yunyin.org/index.php/');
//发送get请求
YYF.success(function(data) {
alert('success:' + data);
}).fail(function(data) {
alert('fail:' + data);
}).get('Index/test');
- 也可以把回调置后
YYF.post('Resource/id', data)
.ready(function(response) {
//do somthing
return true;
}).success(function(data) {
//do somthing when success
}).fail(function(data) {
//do somthing when fail
});
2.2 请求操作 (REST method)
所有请求接口 返回均为当前yyf对象可以继续操作
get(uri, data, async): GET操作post(uri, data, async): POST操作put(uri, data, async): PUT操作patch(uri, data, async): PATCH操作delete(uri,async): DELETE操作request(method, url, data, async): 自定义请求
参数表
| 参数 | 类型 | 默认 | 参数说明 |
|---|---|---|---|
uri |
string |
无(必须) | 请求资源，自动补上全局配置options的root |
data |
Object或string |
undefined |
发送数据,delete无此参数 |
async |
bool |
读取全局配置 | 是否异步请求 |
2.3 回调接口 (callback handler)
所有回调接口 返回均为 当前yyf对象可以继续操作
- invoke回调 (根据条件执行)
success设置操作成功的回调方法fail设置操作失败的回调方法auth设置需要回调的回调方法- 自定义回调
on(statuKey,callback)
- 通用处理 (正常完成一定执行)
ready设置拦截返回内容的回调方法(在success和fail等invoke之前)final处理完成方法(在success和fail等invoke之后)
YYF.setHandle(statuKey,callback)全局设置默认回调方法(优先级最低)
参数细节参照全局回调函数表handle
Configure
配置
3.1 global Configure
- 快速设置API请求站点相对更地址
YYF(root)
/*简单配置*/
//如请求API是index.php ，如果不配置root为"/"
YYF('/index.php/');
//跨站需要带上URL
YYF('https://yyf.yunyin.org/');
- 多参数设置
YYF(options,handle,codeMap)
//基本配置
var options = { //options 参数
root: 'api.php',
type: 'json'
};
// 回调函数
var handlers = { //默认回调
auth: function(data) { //验证失败回调,默认对应status为-1代表验证失败
alert("验证失败,请登录!" + data);
},
error: function(data) { //网络错误或者解析失败
console.log('网络错误:', data);
}
};
// 自定义状态映射表
var codeMap={
success:1
fail:0
};
//options和handler,后面参数可省略
YYF(options,handlers,codeMap);
- 单参数全部设置
YYF({})
//all in one,
YYF({
options: options,
handle: handlers,
code:codeMap
});
3.2 options
全局默认配置，每次请求可能都有同样的设置，可以提前统一配置。
| 键(key) | 类型(type) | 说明 | 默认(value) | 备注 |
|---|---|---|---|---|
root |
string |
请求API地址前缀 | "" |
通常为站点根目录,同站请求无需域名 |
headers |
Object |
附加http头(键值对) | {} |
所有的请求中，添加此请求头 |
cookie |
bool |
(跨域)是否带cookie | false |
仅对跨域设置有效 |
async |
bool |
异步或者同步请求 | true |
false时可阻塞js,根据需要设置 |
status |
string |
返回的状态标识字段 |
"status" |
与服务器上rest.status配置保持一致 |
data |
string |
返回的数据标识字段 |
"data" |
与服务器上rest.data配置保持一致 |
type |
string |
发送请求编码格式 | "urlencoded" |
<li>默认对跨域优化</li><li>json以json格式提交;</li><li>form以表单提交;</li><li>其他为自定义Content-type</li> |
3.3 handle
全局默认回调函数
每次请求可以单独设置这些回调操作，如果没有设置对应处理方式,会使用下面的默认回调方式。
例如，通常,认证失败和网络错误预设一个统一的回调方式来提示用户
| 键(key) | 说明 | 回调参数表 | 默认值(value) | 触发条件和说明 |
|---|---|---|---|---|
onerror |
请求失败或解析出错 | 请求对象 | console.error |
网络，服务器错误或解析出错 |
before |
请求预处理(全局) | data,headers,url,method,XHR |
undefined |
发送请求前调用,可拦截request和修改发送数据 |
ready |
回调拦截,返回false终止分发 | response,res |
undefined |
收到返回数据首先执行此操作 |
final |
所有处理结束后,最后执行 | response,res |
undefined |
返回正常处理最后触发此操作 |
auth |
认证失败默认回调 | data,res |
undefined |
返回status状态为-1(可设置) |
success |
操作成功默认回调 | data,res |
function(){} |
返回status状态为1(可设置) |
fail |
操作失败默认回调 | data,res |
function(){} |
返回status状态为0(可设置) |
| 其他 | 自定义调用(invoke) | data,res |
用户定义函数 | 需自定义状态码，见code配置 |
说明:
before仅可全局配置,不能为某个请求单独设置(此接口通常用来在所有请求中添加统一的校验和,或者验证hash)before可以通过返回值修改数据,如果不存在返回值(不是undefined)则直接复制给请求的数据data- 当返回的response为可解析的json时,
ready和final的第一个参数，传入值为解析后的对象； - 当返回的response为不是json时，
ready和final的第一个参数，传入值为字符串；且不会进入invoke； - invoke 传入的第一个参数,传入值为解析后的数据字段(data)部分.
- 如果设置了
ready,且函数执行返回false(完全===false),可跳过 invoke直接进入final详细流程
3.4 code
状态码表
解析请求结果时，会根据status字段(可以设置options中status字段来修改)不同的值代表不同状态,可以根据需要自定义或者覆盖这些状态码的默认设置
status |
value | 说明 | 操作解释 |
|---|---|---|---|
success |
1 |
操作成功状态码 | 返回中的status为1，触发success回调 |
fail |
0 |
操作失败状态码 | 返回中的status为0，触发fail回调 |
auth |
-1 |
认证失败状态码 | 返回中的status为-1，触发auth回调 |
| 其他string | 自定义值 | 自定状态码 | status为自定义值，调用对应的回调方式 |
同时提供了setCode(code, status)接口来快速设置状态。列如
YYF.setCode(2,'special');
//等效配置
YYF({
code:{special:2}
});
Vue
YYFJS 支持Vue插件
4.1 浏览器中直接使用
引入js库后会自动注册Vue插件
4.2 npm 安装
var Vue = require('Vue');
var YYF = require('yyfjs');
Vue.use(YYF,{/*配置*/});
//或者 YYF(options,callback,code);//配置
4.3 模块内使用
模块内部 使用 this.$yyf即可，相当于调用YYF
exemple
var app = new Vue({
el: '#app',
mounted(){
this.$yyf.get('/');
}
})
Flowchart
基本流程: before()==> [send request] => ready() ==> [INVOKE?]() ==> final()
收到响应(response)后的处理流程：
- before: 发送http请求之前调用，如果有全局before,则调用before,如果有返回值，用来设置data数据
- 发送http请求，等待响应
- ready: 如果存在
ready则先执行ready,返回值为false时直接进入第5步(final)，否则进入第4步(invoke) - invoke: 根据status状态调用对应处理函数，如未定义调用默认配置,如果都未定义直接到第5步(final)
- final：如果存在
final回调函数，则执行此函数，否则结束 - 结束
流程图如下
+~~~~~~~+ +==========+ | START +-------> | before() | +~~~~~~~+ +==========+ | v +----------------------+----+ | RESPONSE <----- REQUEST | +-----------------+---------+ OK | | error +===========+ | +----------> | error() | V +===========+ +-------------+ | | +=========+ | has "ready" | | | | handler ? +------>| ready() | | | YES | | +------+------+ +=========+ NO | | | | v | +============+ +---v----+ | [INVOKE] | | | | -success() | | return | | -fail() | <-------+ FALSE? | | -auth() | NO | | | ... | +---+----+ +============+ | YES | | v |(skip) +------+------+ | | | <----------+ | has "final" | | handler ? | +=========+ | +------->| | +------+------+ YES | final() | NO | | | | +=========+ v | +~~~~+~~~~+ | | DONE | <------------+ +~~~~~~~~~+