mini-iris

安装

$ yarn add mini-iris

或者

$ npm i mini-iris

简介

为小程序平台量身定制的轻量级请求库，请求配置以微信小程序作为标准，其他平台兼容实现。

支持微信小程序、支付宝小程序、百度小程序、字节跳动小程序、QQ 小程序、uniapp。
支持 Typescript，健全的类型系统，智能的 IDE 提示。
支持 Promise。
支持拦截器。
支持取消请求。
支持自定义合法状态码。
支持自定义参数序列化。
支持自定义转换数据。
支持自定义错误处理。
支持自定义平台适配器

使用

如何引入

// esm
import axios from 'mini-iris';
// cjs
const axios = require('mini-iris');
// 使用
axios('/user');

`axios(config)`

可以通过将相关配置传递给axios来发送请求。

// 发送 GET 请求
axios({
  url: "/user",
  method: "get",
  params: {
    id: 1,
  },
})
  .then((response) => {
    // 请求成功后做些什么
  })
  .catch((error) => {
    // 请求失败后做些什么
  });

// 发送 POST 请求
axios({
  url: "/user",
  method: "post",
  data: {
    id: 1,
  },
})
  .then((response) => {
    // 请求成功后做些什么
  })
  .catch((error) => {
    // 请求失败后做些什么
  });

`axios(url, config?)`

也可以通过直接把url传给axios来发送请求。

// 默认发送 GET 请求
axios("/user")
  .then((response) => {
    // 请求成功后做些什么
  })
  .catch((error) => {
    // 请求失败后做些什么
  });

// 发送 POST 请求
axios("/user", {
  method: "post",
})
  .then((response) => {
    // 请求成功后做些什么
  })
  .catch((error) => {
    // 请求失败后做些什么
  });

还可以使用请求方法的别名来简化请求。

axios.request(config)
axios.options(url, config?)
axios.get(url, params?, config?)
axios.head(url, params?, config?)
axios.post(url, data?, config?)
axios.put(url, data?, config?)
axios.delete(url, params?, config?)
axios.trace(url, config?)
axios.connect(url, config?)

常用例子，其他同理：

// 发送 GET 请求
axios.get("/user");

// 携带参数
axios.get("/user", {
  test: 1,
});

// 携带额外配置
axios.get(
  "/user",
  {
    id: 1,
  },
  {
    headers: {
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);

// 发送 POST 请求
axios.post("/user");

// 携带数据
axios.post("/user", {
  id: 1,
});

// 携带额外配置
axios.post(
  "/user",
  {
    id: 1,
  },
  {
    headers: {
      "Content-Type": "application/json; charset=utf-8",
    },
  }
);

动态 URL

您可以使用动态 URL 提高 RESTful API 的书写体验。

axios.get(
  "/user/:id",
  {
    id: 1,
  },
); 

// url => '/user/1?id=1'

配置`config`

非全平台兼容的属性只会在平台支持的情况下生效。

参数	类型	默认值	说明	全平台兼容
adapter	Function	查看	自定义适配器	是
baseURL	String		基础地址	是
url	String		请求地址	是
method	String	get	请求方法
params	Object		请求参数	是
data	String/Object/ArrayBuffer		请求数据	是
headers	Object	查看	请求头	是
validateStatus	Function	查看	自定义合法状态码	是
paramsSerializer	Function		自定义参数序列化	是
transformRequest	Function/Array<.Function>		自定义转换请求数据	是
transformResponse	Function/Array<.Function>		自定义转换响应数据	是
errorHandler	Function		自定义错误处理	是
cancelToken	Object		取消令牌	是
timeout	Number	10000	超时时间
dataType	String	json	响应数据格式	是
responseType	String	text	响应数据类型	是
enableHttp2	Boolean	false	开启 http2
enableQuic	Boolean	false	开启 quic
enableCache	Boolean	false	开启 cache
sslVerify	Boolean	true	验证 ssl 证书

`config.method`的合法值

可以使用大写，也可以使用小写。

值	说明	全平台兼容
OPTIONS
GET		是
HEAD
POST		是
PUT		是
DELETE		是
TRACE
CONNECT

`config.dataType`的合法值

值	说明	全平台兼容
json	返回的数据为 JSON，返回后会对返回的数据进行一次 JSON.parse	是
其他	不对返回的内容进行 JSON.parse	是

`config.responseType`的合法值

值	说明	全平台兼容
text	响应的数据为文本	是
arraybuffer	响应的数据为 ArrayBuffer	是

自定义合法状态码`config.validateStatus`

可以让请求按照您的要求成功或者失败。

axios("/user", {
  validateStatus: function validateStatus(status) {
    // 这样，状态码在 200 到 400 之间都是请求成功
    return status >= 200 && status < 400;
  },
});

自定义参数序列化`config.paramsSerializer`

可以使用自己的规则去序列化参数。

axios("/user", {
  paramsSerializer: function paramsSerializer(params) {
    return qs.stringify(params, {
      arrayFormat: "brackets",
    });
  },
});

自定义转换数据

可以在请求发出之前转换请求数据，在请求成功之后转换响应数据。

axios("/user", {
  transformRequest: [
    function transformRequest(data, headers) {
      // 转换请求数据
      return data;
    },
  ],
  transformResponse: [
    function transformResponse(data) {
      // 转换响应数据
      return data;
    },
  ],
});

自定义错误处理`config.errorHandler`

可以添加到默认配置中，统一处理错误。

axios.defaults.errorHandler = function errorHandler(error) {
  // 做一些想做的事情
  return Promise.reject(error);
};

const instance = axios.create({
  errorHandler: function errorHandler(error) {
    // 做一些想做的事情
    return Promise.reject(error);
  },
});

也可以发送请求时通过自定义配置传入。

axios("/user", {
  errorHandler: function errorHandler(error) {
    // 做一些想做的事情
    return Promise.reject(error);
  },
});

自定义平台适配器`config.adapter`

您可以手动适配当前所处的平台。

axios.defaults.adapter = function adapter(adapterConfig) {
  const {
    // 请求地址
    url,
    // 请求方法
    method,
    // 请求数据
    data,
    // 请求头 同 headers
    headers,
    // 请求头 同 headers
    headers,
    // 响应数据格式
    dataType,
    // 响应数据类型
    responseType,
    // 超时时间
    timeout,
    // 开启 http2
    enableHttp2,
    // 开启 quic
    enableQuic,
    // 开启 cache
    enableCache,
    // 验证 ssl 证书
    sslVerify,
    // 成功的回调函数
    success,
    // 失败的回调函数
    fail,
  } = adapterConfig;

  // 在 adapterConfig 中选择您需要的参数发送请求
  return wx.request({
    url,
    method,
    data,
    headers,
    success,
    fail,
  });
};

// 如果 adapterConfig 的数据结构适用于当前平台，则可以。
axios.defaults.adapter = wx.request;

默认配置`defaults`

全局默认配置`axios.defaults`

axios.defaults.baseURL = "https://www.api.com";
axios.defaults.headers.common["Accept"] = "application/json, test/plain, */*";
axios.defaults.headers.post["Content-Type"] =
  "application/x-www-form-urlencoded; charset=utf-8";

自定义实例默认配置

可以创建时传入。

const instance = axios.create({
  baseURL: "https://www.api.com",
  headers: {
    common: {
      Accept: "application/json, test/plain, */*",
    },
    post: {
      "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
    },
  },
});

也可以创建后修改。

instance.defaults.baseURL = "https://www.api.com";
instance.defaults.headers.common["Accept"] =
  "application/json, test/plain, */*";
instance.defaults.headers.post["Content-Type"] =
  "application/x-www-form-urlencoded; charset=utf-8";

配置优先顺序

发送请求时，会使用默认配置defaults和自定义配置config合并出请求配置requestConfig，然后用合并出的请求配置requestConfig去发送请求，多数情况下，后者优先级要高于前者，具体合并策略可以参考 mergeConfig.ts 的实现。

响应体`response`

非全平台兼容的属性只会在平台支持的情况下生效。

属性	类型	说明	全平台兼容
status	Number	状态码	是
statusText	String	状态文本	是
data	String/Object/ArrayBuffer	开发者服务器返回的数据	是
headers	Object	响应头	是
config	Object	Axios 请求配置	是
cookies	Array<.String>	开发者服务器返回的 cookies，格式为字符串数组
profile	Object	网络请求过程中一些关键时间点的耗时信息

API

`axios.interceptors`

可以先拦截请求或响应，然后再由 then 或 catch 处理。

// 添加请求拦截器
axios.interceptors.request.use(
  function(config) {
    // 在发送请求之前做些什么
    return config;
  },
  function(error) {
    //处理请求错误
    return Promise.reject(error);
  }
);

// 添加响应拦截器
axios.interceptors.response.use(
  function(response) {
    // 请求成功后做些什么
    return response;
  },
  function(error) {
    // 处理响应错误
    return Promise.reject(error);
  }
);

如果以后需要删除拦截器，则可以。

const myInterceptor = axios.interceptors.request.use(function() {
  // 在发送请求之前做些什么
});
axios.interceptors.request.eject(myInterceptor);

还可以将拦截器添加到axios的自定义实例中。

const myInterceptor = instance.interceptors.request.use(function() {
  // 在发送请求之前做些什么
});
instance.interceptors.request.eject(myInterceptor);

`axios.CancelToken`

可以使用CancelToken取消已经发出的请求。

let cancel;

axios("/api", {
  cancelToken: new axios.CancelToken(function(c) {
    cancel = c;
  }),
});

cancel("取消请求");

还可以使用CancelToken.source工厂方法创建CancelToken。

const source = axios.CancelToken.source();

axios("/api", {
  cancelToken: source.token,
});

source.cancel("取消请求");

`axios.isCancel`

可以判断当前错误是否来自取消请求

axios("/user").catch((error) => {
  if (axios.isCancel(error)) {
    // 请求被取消了
  }
});

`axios.getUri(config)`

根据配置中的url和params生成一个URI。

const uri = axios.getUri({
  url: "/user",
  params: {
    id: 1,
  },
});
// '/user?id=1'

`axios.create(defaults)`

创建一个自定义实例，传入的自定义默认配置defaults会和axios的默认配置axios.defaults合并成自定义实例的默认配置。

自定义实例拥有和axios相同的调用方式和请求方法的别名。

axios.defaults.baseURL = "https://www.api.com";

const instance = axios.create({
  params: {
    id: 1,
  },
});

instance("/user");
// 'https://www.api.com/user?id=1'

`axios.Axios`

axios.Axios是一个类，其实axios就是axios.Axios类的实例改造而来的，axios.create(defaults)创建的也是axios.Axios的实例。

直接实例化axios.Axios可以得到一个原始实例，不能当函数调用，传入的自定义配置就是原始实例的默认配置，而不会像axios.create(defaults)一样去合并axios中的默认配置。

const instance = new axios.Axios({
  beseURL: "https://www.api.com",
  params: {
    id: 1,
  },
});

instance.get("/user");
// 'https://www.api.com/user?id=1'

执行流程

axios("/user")
  .then()
  .catch();

// 请求成功
// axios => axios.interceptors.request => config.transformRequest => config.paramsSerializer => config.adapter => config.validateStatus => config.transformResponse => axios.interceptors.response => then

// 请求失败
// axios => axios.interceptors.request => config.transformRequest => config.paramsSerializer => config.adapter => config.validateStatus => config.transformResponse => config.errorHandler => axios.interceptors.response => catch

zhiyouth/mini-iris

mini-iris

安装

简介

使用

如何引入

axios(config)

axios(url, config?)

axios.request(config)

axios.options(url, config?)

axios.get(url, params?, config?)

axios.head(url, params?, config?)

axios.post(url, data?, config?)

axios.put(url, data?, config?)

axios.delete(url, params?, config?)

axios.trace(url, config?)

axios.connect(url, config?)

动态 URL

配置config

config.method的合法值

config.dataType的合法值

config.responseType的合法值

自定义合法状态码config.validateStatus

自定义参数序列化config.paramsSerializer

自定义转换数据

自定义错误处理config.errorHandler

自定义平台适配器config.adapter

默认配置defaults

全局默认配置axios.defaults