axios-miniprogram

安装

$ yarn add axios-miniprogram

或者

$ npm i axios-miniprogram

简介

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

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

使用

如何引入

// esm
import axios from 'axios-miniprogram';
// cjs
const axios = require('axios-miniprogram');
// 使用
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