This package has been deprecated

Author message:

This module has moved and is now available at @wxhccc/smartfetch. Please update your dependencies as this version is no longer maintained an may contain bugs and security issues.

smartfetch

an easy use api plugin for vue and react.

Installing

use npm

$ npm install smartfetch

使用示例

在vuejs中使用

install the plugin in main.js

import Vue from 'vue'
...
import smartfetch from 'smartfetch'

/** 配置文件推荐使用独立文件 **/

import { Notification } from 'element-ui';  // 错误提示可按需求选择ui库组件实现
const statusMsgs = {
  '404': '请求地址不存在',
  '500': '服务器维护中，请稍后再试'
};
const codeMsgs = {
  'E001': '未登录'
};
const useConfig = {
  baseConfig: {  // 基础配置对象，多份配置可使用数组
    baseURL: ''
  },
  /*baseConfig: [  // 多配置时key是必须的，用来切换配置
    {
      key: 'default',  // 'default' 是默认配置的key
      baseURL: 'url1'
    },
    {
      key: 'upload'
      baseURL: 'url2'
    }
  ]*/
  baseData: {},  // 基础数据，会随着所有请求发送，适合无法再header里添加token的场景。 可以为数据对象，或者函数
  errorHandle: notifyMsg, // 统一错误处理，优先级低于codeError
  statusWarn: statusMsgs, // response对象status值转换对象，用于自定义status文案
  resCheck: 'success', // 返回值检测，用于过滤通用接口数据， 可以为函数
  forceAxios: true, // 是否强制使用axios核心发送请求，默认false
  dataKey: 'data',  // 数据字段，默认'data'
  codeError: (resjson) => { /* 业务逻辑错误码处理函数, resCheck检测未通过时会执行 */ 
    let {errorCode, errorMsg} = resjson;
    let msg = errorMsg || '请求失败';
    if (codeMsgs.hasOwnProperty(errorCode)) {
      let valType = typeof codeMsgs[errorCode];
      if (valType === 'string') {
        msg = codeMsgs[errorCode];
        notifyMsg(msg);
      } else if(valType === 'function') {
        codeMsgs[errorCode]();
      }
    } else {
      notifyMsg(msg);
    }
  }
}

Vue.use(smartfetch, useConfig);
...

use in the component

    <button :disabled="loading">{loading ? 'sending' : 'send'}</buttom>
...
    data () {
      return {
      	loading: false
      }
    }
...
    mounted() {
      this.$fetch({url: 'api/test', data: {user: 'aaa'}})
      	  .lock('loading')  // 发送请求前锁住当前实例状态中的loading字段，请求完成后（成功/失败）会释放
      	  .done((data) => { 
          /* 
            接口请求成功且通过业务逻辑检测(业务逻辑检测可关闭)后运行，参数为返回数据的payload，例如：接口返回{ code: 2000, message: '', data: { id: 111} }，data就是{ id: 111}
          */
      	  	// todo
      	  })
      	  .silence() /* 静默接口，会忽略所有错误处理逻辑（faile函数仍能获取错误信息），适用于不需要或不适合弹出错误提示的场景 */
      	  .faile((error)=>{
          /* 如果你需要自己处理特定接口的错误，可使用此函数 */
      	  }) 
      	  .notCheckCode() /* 不进行业务逻辑code检测，适用于调用第三方接口或返回值和系统约定结构不一致的场景 */
        .finally(() => {
          /* 接口调用无论成功或失败都会执行的代码 */
        })
    }
...

API document

options 基础配置对象

baseConfig: 基础配置对象. 可用来设置统一的 baseURL 、 headers 等. 接收对象或对象数组

示例：

// 使用对象方式，单一配置项
baseConfig: {
  baseURL: 'http://a.b.com',
  headers: {x-token: 'xxxxxxx'}
}
/* 使用数组，多配置项，此时对象中key为必须字段
** *default* 是key的特殊值, key为default的配置项为默认配置项
** 可以使用 **useCore(key)** 方法切换配置项
*/
baseConfig: [
  {
    key: 'default',  
    baseURL: 'http://a.b.com'
  }, {
    key: 'upload',
    baseURL: 'http://a.bcd.com'
  }
]

ps: 在一些场景下，你可能在初始化之后才能获取基础配置信息，比如登录后才能获取token。这时你可以使用示例上的 "modifyBaseConfigs" 方法来修改基础配置（详细用法后面介绍）

baseData: 基础请求数据，会合并到所有请求中。适用于特殊情况无法通过headers附带的数据，比如未支持特定header的cors接口。可支持对象或函数

示例：

// 使用对象
baseData: {
  token: 'xxxxxxxxxxx',
}
// 使用函数

baseData: () => {
  const token = Math.random();
  return {
    token
  }
}

errorHandle: 通用错误提示函数，用来显示/处理接口调用过程中的错误信息

参数：

• @message(string)：插件处理过后的错误提示,可直接使用插件显示
• @error(Error)： 错误对象，如果需要自己处理特定错误可使用

  error可能是TypeError（请求发送前失败，axios核心下是Error），SyntaxError(语法错误，比如接口返回json字符串格式错误)，RangeError(status值不在有效返回，有效范围通过配置项中的validateStatus参数设置)，CodeError(业务逻辑code检测失败)，CallbackSyntaxError(done或faile函数的回调函数中存在语法错误)等类型

• @response(HTTP response): 请求响应对象，可用于获取status具体值

示例：

errorHandle: (msg, error) => {
  alert(msg)
  /* or 
  Notification.error({
    title: '系统提示',
    message: msg
  }) // element-ui库中组件
  */
}

statusWarn: http协议中响应对象中状态码（status）对应提示文案，用于定制特定的status提示语

示例：

statusWarn: {
  '401': '亲，未登录无法访问哟！',
  '404': '抱歉接口地址不存在'
  ....
}

resCheck: 业务逻辑检测,适用于接口有统一数据结构，例如{ success: true, code: 200, message: '', data: {} }。接受字符串或函数，为字符串时或判断对象里指定key对应value值是否为真值

示例：

// 使用字符串时，会检查responseData[resCheck]是否是真值
resCheck: 'success'

// 使用函数，参数为请求响应对象中的数据对象
resCheck: (responseData) => {
  return responseData.code === 200
}

dataKey: 统一结构下实际数据值的key，默认为data

forceAxios: 是否强制使用axios为请求核心，默认为false

codeError: 业务逻辑检测失败时的处理函数，resCheck检测失败时触发，优先级高于errorHandle处理函数

示例：

codeError: (resJson) => {
  // to do
}

request

插件导出的工具方法，用于简化请求参数和让接口定义更规范化

参数：

• @url(string)：接口路径，可使用完整路径，也可使用相对于baseUrl的相对路径
• @data(object/FormData): 请求参数，仅支持plain object. formData
• @method(string): 请求方式，支持所有请求方式，例如GET、POST等，全大写，默认GET
• @returnLink(boolean)：是否返回完整链接，仅对GET,HEAD方式有效，函数调用后不发起请求，会返回拼接好的携带参数的url地址。常用作下载或导出链接
• @enctype(string)：请求编码方式（content-type设定值），json = 'application/json', urlencode: 'application/x-www-form-urlencoded', text: 'text/plain'，默认为json

request(config)

用于设置request函数配置的高阶函数，会返回request函数

高阶函数参数：

• @config(object) 用于配置request的对象
  • useCore: 用于发送请求的配置项的key

如何使用

import { request } from 'smartfetch'
//// 例 1:
// 正常请求
const args = request('api/getxxx', {a: 1, b: 2}, 'GET')
this.$fetch(args)

//// 例 2:
// 返回链接
const linkUrl = request('api/getxxx', {a: 1, b: 2}, 'GET', true)
// linkUrl: http://a.b.com/api/getxxx?a=1&b=2

//// 例 3:
// 高阶函数方式，request({})调用后会返回修改配置后的request函数本身，用于在定义时指定请求使用的配置项
const args = request({useCore: 'upload'})('api/getxxx', {a: 1, b: 2}, 'GET')
this.$fetch(args)
// 请求会使用key为upload的配置项, 例如'http://a.bcd.com/api/getxxx'

推荐模式

在独立文件中定义接口函数

import { request } from 'smartfetch'

export function getUserList (data) {
  return request('api/users', data)
}
export function addUser (data) {
  return request('api/users', data, 'PUT')
}

在指定路由页面

...
// 从指定文件中引入接口函数
import { getUserList } from '@/api/xxxx'
...

this.$fetch(getUserList, { xxx: 'xxx' }).lock('loading').done(data => {
  // to do
})

fetch

请求发起函数

使用方式

使用实例方式，无依赖环境

import { SmartFetch } from 'smartfetch'

const options = {
  // configs
}
const smartfetch = SmartFetch(options)

smartfetch.fetch({
  url: 'api/getxxx',
  data: { a: 1 }
})

在vuejs中使用

在main.js中安装

...
import smartfetch from 'smartfetch'
const options = {
  // configs
}
Vue.use(smartfetch, options)

// 之后再各组件中使用$fetch发起请求
this.$fetch
...

Smartfetch实例方法

以下为SmartFetch类示例方法列表

resetOpts

说明: 用来重置示例配置 参数： @options(object)，配置对象，具体说明见上

fetch

说明: 请求发起函数
参数

方式一

• @config(object) 请求对象

方式二

• 第一个参数非对象时会内部调用requset来得到config, 具体见request普通参数列表

方式三

• @requestFn(function)， 第一个参数为使用request封装的函数时，后续参数会按顺序传递给requestFn

如何使用

//// 例 1:
// if the first argument is object
const args = {
  url: 'api/getxxx',
  data: {a: 1, b: 2},
  method: 'POST')
}
this.$fetch(args)
// or
smartfetch.fetch(args)

//// 例 2:
// if the first argument is a string , fetch will use *request* to handle arguments
this.$fetch('api/getxxx', {a: 1, b: 2}, 'GET')

//// 例 3:
// if the first argument is a function , fetch will put rest arguments to the function, can use with request to make apis more clear
const request1 = function(data) {
  return request('api/getxxx', data, 'GET')
}
this.$fetch(request1, {a: 1, b: 2})

modifyBaseConfigs

说明: 你可以使用此函数来修改基础配置项
参数： 基础配置项对象/数组

如何使用

import smartfetch from 'smartfetch'
smartfetch.modifyBaseConfigs(baseConfigs => {
  // single config
  baseConfigs.headers.token = 'xxx'
  // configs array
  baseConfigs.forEach(item => {
    item.headers.token = 'xxx'
  })
})

fetch函数返回示例的方法列表

说明：调用fetch函数后会返回一个请求代理对象，对象会提供下列方法，方法调用后会返回对象本身（除promise外），可使用链式调用。在所有链式同步代码执行完后开始发起请求，链式调用无先后顺序。

lock

说明： 重要常用函数。用来锁住当前实例上下文中指定key的变量，在发起请求前设置成true，请求完成后设置为false。可用来处理loading状态和防多点需求 params: @key(string): 实例上指定属性名，支持.写法写法，如a.b

如何使用

// use in vuejs
...
data: () {
  return {
    loading: false
  }
}
...
  this.$fetch('api/getxxx', data).lock('loading')

// use in react
...
this.state = {
  loading: false
}
    
...
  smartfetch.fetch('api/getxxx', data).lock('loading')

useCore

说明: 用于切换基础配置

params: @key(string): baseConfig key

  this.$fetch(arg).useCore('upload')

silence

说明: 开启静默模式

notCheckCode

说明: 不进行业务逻辑检测，适用于调用第三方接口

done

说明: 请求成功后，并且通过业务逻辑检测（如果有的话）后会执行参数传入的回调函数

params: @callback(function) 回调函数，参数为返回数据中指定key对应内容 @data(any)

fail

说明: 请求成功后，并且通过业务逻辑检测（如果有的话）后会执行参数传入的回调函数

params: @callback(function) 回调函数，参数为错误对象error

finally

说明: 无论请求成功或失败都会调用。适用于特定场景下变量锁

params: @callback(function) 回调函数，无参数

promise

说明: 调用函数后会将请求的promise对象返回。

警告： 调用此方法后无法继续链式调用