1.3.5 • Published 3 years ago

yyfjs v1.3.5

Weekly downloads
5
License
Apache-2.0
Repository
github
Last release
3 years ago

YYFJS

YYF前端请求和数据接口封装JS库。

The frontend JavaScript library for YYF RESTful API request.

Build Status npm lib size lib gzip size

  1. 安装和使用
  2. 接口API
  3. 配置
  4. Vue插件
  5. 流程图

在线演示示例:


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(示例)

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

  • 快速定义
YYF('https;//yyf.yunyin.org/index.php/');
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): 自定义请求

参数表

参数类型默认参数说明
uristring无(必须)请求资源,自动补上全局配置optionsroot
dataObjectstringundefined发送数据,delete无此参数
asyncbool读取全局配置是否异步请求

2.3 回调接口 (callback handler)

所有回调接口 返回均为 当前yyf对象可以继续操作

  • invoke回调 (根据条件执行)
    • success设置操作成功的回调方法
    • fail设置操作失败的回调方法
    • auth设置需要回调的回调方法
    • 自定义回调 setHandle(key,callback)
  • 通用处理 (正常完成一定执行)
    • ready设置拦截返回内容的回调方法(在success和fail等invoke之前)
    • final处理完成方法(在success和fail等invoke之后)

参数细节参照全局回调函数表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);
    },
    onerror: function(data) { //网络错误或者解析失败
        console.log('网络错误:', data);
    }
};
//options和handler,后面参数可省略
YYF(options, handlers);
  • 单参数全部设置YYF({})
//all in one,
YYF({
    options: options,
    handle: handlers
});

3.2 options

全局默认配置,每次请求可能都有同样的设置,可以提前统一配置。

键(key)类型(type)说明默认(value)备注
rootstring请求API地址前缀""通常为站点根目录,同站请求无需域名
headersObject附加http头(键值对){}所有的请求中,添加此请求头
cookiebool(跨域)是否带cookiefalse仅对跨域设置有效
asyncbool异步或者同步请求truefalse时可阻塞js,根据需要设置
statusstring返回的状态标识字段"status"与服务器上rest.status配置保持一致
datastring返回的数据标识字段"data"与服务器上rest.data配置保持一致
typestring发送请求编码格式"urlencoded"默认对跨域优化json以json格式提交;form以表单提交;其他为自定义Content-type

3.3 handle

全局默认回调函数

每次请求可以单独设置这些回调操作,如果没有设置对应处理方式,会使用下面的默认回调方式。

例如,通常,认证失败和网络错误预设一个统一的回调方式来提示用户

键(key)说明回调参数表默认值(value)触发条件和说明
onerror请求失败或解析出错请求对象console.error网络,服务器错误或解析出错
before请求预处理(全局)data,headers,url,method,XHRundefined发送请求前调用,可拦截request和修改发送数据
ready回调拦截,返回false终止分发response,resundefined收到返回数据首先执行此操作
final所有处理结束后,最后执行response,resundefined返回正常处理最后触发此操作
auth认证失败默认回调data,resundefined返回status状态为-1(可设置)
success操作成功默认回调data,resfunction(){}返回status状态为1(可设置)
fail操作失败默认回调data,resfunction(){}返回status状态为0(可设置)
其他自定义调用(invoke)data,res用户定义函数需自定义状态码,见code配置

说明:

  • before 仅可全局配置,不能为某个请求单独设置(此接口通常用来在所有请求中添加统一的校验和,或者验证hash)
  • before 可以通过返回值修改数据,如果不存在返回值(不是undefined)则直接复制给请求的数据data
  • 当返回的response为可解析的json时, readyfinal的第一个参数,传入值为解析后的对象;
  • 当返回的response为不是json时,readyfinal的第一个参数,传入值为字符串;且不会进入invoke;
  • invoke 传入的第一个参数,传入值为解析后的数据字段(data)部分.
  • 如果设置了ready,且函数执行返回false(完全===false),可跳过 invoke直接进入final 详细流程

3.4 code

状态码表

解析请求结果时,会根据status字段(可以设置optionsstatus字段来修改)不同的值代表不同状态,可以根据需要自定义或者覆盖这些状态码的默认设置

statusvalue说明操作解释
success1操作成功状态码返回中的status为1,触发success回调
fail0操作失败状态码返回中的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)后的处理流程:

  1. before: 发送http请求之前调用,如果有全局before,则调用before,如果有返回值,用来设置data数据
  2. 发送http请求,等待响应
  3. ready: 如果存在ready则先执行ready,返回值为false时直接进入第5步(final),否则进入第4步(invoke)
  4. invoke: 根据status状态调用对应处理函数,如未定义调用默认配置,如果都未定义直接到第5步(final)
  5. final:如果存在final回调函数,则执行此函数,否则结束
  6. 结束

流程图如下

      +~~~~~~~+         +==========+
      | START +-------> | before() |
      +~~~~~~~+         +==========+
                             |
                             v
      +----------------------+----+
      | RESPONSE  <-----  REQUEST |
      +-----------------+---------+
        OK |            | error      +===========+
           |            +----------> | onerror() |
           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   | <------------+
      +~~~~~~~~~+
2.1.2-beta

3 years ago

1.3.5

3 years ago

2.1.1-beta

3 years ago

2.1.0-beta

4 years ago

1.3.4

4 years ago

1.3.2

4 years ago

2.0.0-beta

4 years ago

1.1.22

4 years ago

1.1.22-beta.5

4 years ago

1.1.2-2.beta.5

4 years ago

1.1.22-beta.4

4 years ago

1.1.22-beta.3

4 years ago

1.1.22-beta.2

4 years ago

1.1.22-beta

4 years ago

1.1.20

4 years ago

1.1.2

4 years ago

0.2.0

4 years ago

0.1.0

4 years ago

0.0.1

4 years ago