Skip to content

suboat/resource

BranchesTags

Repository files navigation

基于原生XMLHTTPRequest,ES6语法编写，符合restful接口的http库

文档目录

  1. 使用方法
  2. $resource
    1. 属性
      1. responseType
      2. headers
      3. withCredentials
      4. hosts
      5. interceptor
      6. transformHeaders
      7. q
      8. $q
      9. $utils
    2. 方法
      1. $resource()
        1. $resource的实例
      2. $resource.register()
      3. $resource.$http()
  3. response的数据结构
  4. demo
    1. 获取一个json文件
    2. 获取某个用户信息
    3. 自定义某个API的headers
    4. 指定某个action的请求头
    5. 指定某个api的缓存
  5. 构建项目
  6. 测试

使用方法

bower:

// 尚未上传至bower
bower install resource

npm:

// 尚未上传至npm
bower install resource
import $resource from 'resource';
// or
var $resource = require('resource');

$resource对象

整包输出$resource对象

分别以3中情况输出

  • AngularJs

    自动生成一个$resource模块，里面有$resource服务

    • $resourceProvider

      • .setResponseType(type)

        设置响应类型

      • .setHeaders(headers)

        设置全局的请求头

      • .setWithCredentials(boolean)

        设置是否跨域

      • .setHosts(hosts)

        设置API地址

      • .setInterceptor(func)

        设置响应拦截器

      • .setTransformHeaders(func)

        设置默认的请求头转换器

    • $resource

      $resource服务就是$resource

  • jQuery

    挂载到 $.fn.$resource 下

  • window

    以上两个条件都不满足，则挂载在全局作用于下

$resource的属性

responseType

设置响应类型，默认为:'',比如设置为json

$resource.responseType='json';

可选的responseType

  • ''
  • 'text'
  • 'arraybuffer'
  • 'blob'
  • 'document'
  • 'json'

headers

设置全局的请求头，默认值:{Accept: 'application/json, text/plain, text/html, */*'}

$resource.headers = {
  admin:true
}

withCredentials

设置是否跨域，默认值：false

$resource.withCredentials = true;

hosts

设置接口的hosts地址，默认值：window.location.host

$resource.hosts = 'localhost:8080';

interceptor

设置对response的拦截器

  • response，不是纯粹的response，而是经过包装之后。结果与ngResource包装的基本一致

    response的数据结构

  • $q，promise的Q库

  • return

    • promise
      • 如果promise为reject，则调用的then为reject，resolve也一样
      • 如果带data$q.resolve(data)，则最后调用的结果就是data
    • boolean
      • 如果为true，则视为resolve，为false视为reject
      • data默认为response
      • return false 等效于 return $q.reject(response)
      • return true 等效于 return $q.resolve(response)
    • any
      • 结果既不是promise，也不是boolean
      • 一律视为reject，reject的data则为返回的值
      • return undefined 等效于 return $q.reject(undefined)
/**
* 默认拦截器
* @param response
* @param $q
* @returns {* | boolean | promise}
*/
$resource.interceptor = function(response, $q){
    if (!response || response.status >= 400 || !response.data) {
      return $q.reject();
    } else {
      return $q.resolve();
    }
}

transformHeaders

对请求头的转换器

这个是全局的，意味着，发出的每一个请求，含有头部信息，都会经过这个列表的函数变形

默认为空数组:[]

/**
* 对请求头的数据，进行转换
* @param headers          请求头
* @returns {*}        可以返回任意值，返回的值会经过下一轮的转换器转换，最后输出最终值
*/
var transform = function(headers){
  // 给所有 headers 添加 test = 'test'
  headers.test = 'test';
  return headers
}
$resource.transformHeaders.push(transform)

q

$resource.q

返回通过$resource.register(id,url,params,actions,options)注册的api

$QQ

$resource.$q

返回 Q库

用于操作promise

$utils

$resource.$utils

内部的工具集合

var $utils = $resource.$utils;
console.log($utils);
{
  noop,
  isDefined,
  isUndefined,
  isArray,
  isDate,
  isBoolean,
  isElement,
  isNumber,
  isObject,
  isString,
  isFunction,
  isRegExp,
  isWindow,
  isFile,
  isBlob,
  isTypedArray,
  isArrayBuffer,
  equals,
  merge,
  extend,
  copy,
  forEach,
  fromJson,
  toJson
}

$resource的方法

register

$resource.register(id,url,params,actions,options)

注册api，对$resource的一层包装

  • id:string

    • 必填，注册api的唯一标识符

  • url:string

    • 必填，api的url地址，为相对地址，比如'/:path/:file.json'

  • params:object

    • 绑定url中的通配符至传入到调用方法的params

  • actions:object

    • 自定义方法
    {action1: {method:?, params:?, isArray:?, headers:?, ...},
 action2: {method:?, params:?, isArray:?, headers:?, ...},
 ...}
    • 默认的actions
    var defaultActions = {
  get: {method: 'GET'},
  query: {method: 'GET'},
  post: {method: 'POST'},
  save: {method: 'POST'},
  create: {method: 'POST'},
  put: {method: 'PUT'},
  update: {method: 'PUT'},
  fetch: {method: 'GET'},
  delete: {method: 'DELETE'},
  remove: {method: 'DELETE'},
  options: {method: 'OPTIONS'},
  head: {method: 'HEAD'},
  patch: {method: 'PATCH'},
  trace: {method: 'TRACE'},
  connect: {method: 'CONNECT'},
  move: {method: 'MOVE'},
  copy: {method: 'COPY'},
  link: {method: 'LINK'},
  unlink: {method: 'UNLINK'},
  wrapped: {method: 'WRAPPED'},
  'extension-mothed': {method: 'Extension-mothed'}
}

  • options:object

    自定义配置，通过该api注册的所有方法，都通过这个配置，优先级低于actions

    • headers:object

      • 设置请求头

    • interceptor:function

      • 设置拦截器，通过这个api的方法，都使用这个拦截器

    • withCredentials：boolean

      • 设置是否跨域

    • transformHeaders:array

      对请求头进行变形，详情参考transformHeaders

      设置了该参数，不会覆盖全局的$resource.transformHeaders，而是依次变形，得到最终结果

  • return：返回一个new $resource(url,params,actions,options)

$resource

new $resource(url,params,actions,options)

生成一个$resource实例

  • url:与$resource.register一致

  • params：与$resource.register一致

  • actions：与$resource.register一致

  • options：与$resource.register一致

  • return

    返回一个内部的Http对象

$resource实例

$resource的实例为一个内部的Http对象

该Http对象的原型(prototype)包含了所有actions的方法，包括默认actions和自定义actions

例如new $resource(url,params,actions,options).get().$promise.then();

例如new $resource(url,params,actions,options).post().$promise.then();

例如new $resource(url,params,actions,options).put().$promise.then();

Http[action](params,config)

  • action 方法，如get，post，put...

  • params 参数，用于解析url地址，如果为post,put等方法，则会作为requestBody随着请求发送服务器

    例如： url:'/user/:uid'

    params:{uid:'testUser'}

    则会把地址解析成'/user/testUser'

  • config 配置项，与 $resource(url,params,actions,options) 中的 options一致

    配置了该属性，会覆盖全局设置和$resource的options中的设置

    属于临时配置项，临时配置当前调用的方法

    transformHeaders 详情参考transformHeaders 设置了该参数，不会覆盖全局的$resource.transformHeaders和$resource的options设置的变形器，而是依次变形，得到最终结果

$http

$resource的底层方法，每个$resource实例，都会调用$http

$resource.$http(config);

  • config
    • url
    • method
    • headers
    • withCredentials
    • data
    • interceptor
    • timeout(尚未实现)
    • eventHandlers
    • cache
    • responseType
  • return
    • response.resource
      • $promise
      • $resolve
      • ...(response.data)

response的数据结构

var userApi = new $resource('/user/:uid',{uid:'@uid'});
userApi.get({user:'testUser'}).$promise
    .then(function(response){
      console.log(response);
    },function(response){
      console.error(response);
    });

response

  • $$XHR：XMLHttpRequest
  • config
    • cache:boolean|number,是否缓存，为数字时，表示缓存次数
    • data:any,requestBody的数据
    • headers:object，请求头
    • method:string，请求方法
    • responseType:string，响应类型
    • url:string，请求的url地址
    • withCredentials:boolean，是否跨域
  • data:any，真正的后台返回的数据
  • headers:object
  • resource
    • $promise:promise
    • $resolve:boolean
    • ...(response.data)
  • status:number，状态码
  • statusText:string，状态提示文本

例子

获取一个json文件

var getJson = $resource.register('getJson','/data/:file.json');
getJson.get({file:'demo'}).$promise
    .then(function(resp){
      var json = resp.data;
      console.log(json);
    },function(error){
      console.log(error);
    });

通过new $resource()的方法

var getJson = new $resource('/data/:file.json');
getJson.get({file:'demo'}).$promise
    .then(function(resp){
      var json = resp.data;
      console.log(json);
    },function(error){
      console.log(error);
    });

获取某个用户信息

var getUser = $resource.register('userApi','/user/:uid');
getUser.get({uid:'testUser'}).$promise
    .then(function(resp){
      console.log(resp);
    },function(error){
      console.error(error);
    });

自定义某个API的headers

var getUser = $resource.register('userApi','/user/:uid',{uid:'@uid'},{},{
  headers:{
    auth:'test'
  }
});
getUser.get({uid:'1'}).$promise
    .then(function(resp){
      console.log(resp);
    },function(error){
      console.error(error);
    });

通过getUser调用的所有方法，请求头都会加上{auth:'test'},比如

getUser.get();
getUser.post();
getUser.put();
...

指定某个action的请求头

var getUser = $resource.register('userApi','/user/:uid',{uid:'@uid'},{
  // 自定义的actions
  info:{
    method:'GET',
    headers:{
      auth:'test'
    }
  }
});

// info方法，会添加请求头{auth:'test'}

getUser.info({uid:'1'}).$promise
    .then(function(resp){
      console.log(resp);
    },function(error){
      console.error(error);
    });

指定某个api的缓存

// 设置缓存次10次
var getUser = $resource.register('userApi','/user/:uid',{uid:'@uid'},{},{
  cache:10
});

// 10次之后的请求，都会被缓存，直到超过缓存次数
getUser.get().$promise
getUser.post().$promise
getUser.put().$promise

构建项目

git clone https://github.com/suboat/resource.git
cd resource
npm install
npm run build

测试

npm test

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

4 watching

Forks

0 forks
Report repository

Releases 4

0.3.3 Latest
Apr 27, 2016
+ 3 releases

Packages

No packages published

Languages