更新记录

v2.0.0-rc-2(2021-06-30)

fix: 修复正则导致的问题

1.3.1(2021-04-10)

fix:修复动态 URL 错误匹配端口号的问题

查看更多

平台兼容性

axios-miniprogram

build status Coverage Status npm version License: MIT

安装

$ yarn add axios-miniprogram

或者

$ npm i axios-miniprogram

简介

小程序平台专用请求库,实现了 axios 大部分功能,用法只存在少许差异,如果您是 axios 的老用户,那么不需要学习就可以直接上手使用。

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

使用

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
    header,
    // 请求头 同 header
    headers,
    // 响应数据格式
    dataType,
    // 响应数据类型
    responseType,
    // 超时时间
    timeout,
    // 开启 http2
    enableHttp2,
    // 开启 quic
    enableQuic,
    // 开启 cache
    enableCache,
    // 验证 ssl 证书
    sslVerify,
    // 成功的回调函数
    success,
    // 失败的回调函数
    fail,
  } = adapterConfig;

  // 在 adapterConfig 中选择您需要的参数发送请求
  return wx.request({
    url,
    method,
    data,
    header,
    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)

根据配置中的urlparams生成一个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

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

MIT协议

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问