applets-request

基于Promise API 的接口请求组合库，对外接口和用法与axios类似；

Note: 该库没有实现adapter，开发者需要自行实现

如果不想实现adapter的，可以直接使用applets-request-all，该库支持大部分小程序请求，weapp、wechat、alipay、百度小程序、抖音/头条小程序。点击查看applets-request-all

Features

• 支持 Promise API
• Interceptor request and response
• Transform request and response data
• Transform Config
• Cancel requests
• Automatic transforms for JSON data

Installing

Using npm:

npm install applets-request

Using yarn:

yarn add applets-request

Example

GET Request：

import appletsRequest from "applets-request-all";

// 获取一篇博客文章：
appletsRequest
  .get("/article?articleId=1")
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });

// 使用可选参数发送请求
appletsRequest
  .get("/article", {
    params: {
      articleId: 1,
    },
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });

// 使用async/await
async function queryArticle() {
  try {
    const response = await appletsRequest.get("/article?articleId=1");
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

POST Request:

import appletsRequest from "applets-request-all";

appletsRequest
  .post("/user", {
    username: "tom",
    password: "********",
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });

// 同时执行多个请求
function queryUser() {
  return appletsRequest.get("/user/12345");
}

function queryArticle() {
  return appletsRequest.get("/article/1");
}

Promise.all([queryUser(), queryArticle()]).then(function (results) {
  const user = results[0];
  const article = results[1];
});

appletsRequest API

appletsRequest本身是function，可以直接调用，发送请求：

appletsRequest(config)

// Send a POST request
appletsRequest({
  method: "post",
  url: "/user/12345",
  data: {
    username: "tom",
    password: "********",
  },
});

// Send a GET request
appletsRequest({
  method: "get",
  url: "/article",
  params: {
    articleId: 1,
  },
  responseType: "json",
})
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .then(function () {
    // always executed
  });

appletsRequest(url[,config])`

// Send a GET request (default method)
appletsRequest("/user/12345");

Request method aliases

可以使用别名直接发送请求；

• appletsRequest.request(config);
• appletsRequest.get(url[, config]);
• appletsRequest.delete(url[, config]);
• appletsRequest.head(url[, config]);
• appletsRequest.options(url[, config]);
• appletsRequest.post(url[, data[, config]);
• appletsRequest.put(url[, data[, config]);

特别注意：使用别名方法时，不要在config中重新配置url method和data属性值。

Request Config

下面列举的是config中所有有效的配置，其中只有url属性是必传的，如果method不传，默认为get

{
  // `url` is the server URL that will be used for the request
  // 可以是绝对路径
  url: '/user',

  // `method` is the request method to be used when making the request
  method: 'get', // default

  // `baseURL` will be prepended to `url` unless `url` is absolute.
  // It can be convenient to set `baseURL` for an instance of appletsRequest to pass relative URLs
  // to methods of that instance.
  // 如果url是绝对路径，该值将被忽略
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest` allows changes to the request data before it is sent to the server
  // This is only applicable for request methods 'PUT', 'POST', 'PATCH' and 'DELETE'
  // The last function in the array must return a string or an instance of Buffer, ArrayBuffer,
  // FormData or Stream
  // You may modify the headers object.
  transformRequest: [function (data, headers) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `transformResponse` allows changes to the response data to be made before
  // it is passed to then/catch
  transformResponse: [function (data) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `headers` are custom headers to be sent
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` are the URL parameters to be sent with the request
  // Must be a plain object or a URLSearchParams object
  params: {
    ID: 12345
  },

  // `paramsSerializer` is an optional function in charge of serializing `params`
  // (e.g. https://www.npmjs.com/package/qs, http://api.jquery.com/jquery.param/)
  paramsSerializer: function (params) {
    return Qs.stringify(params, {arrayFormat: 'brackets'})
  },

  // `data` is the data to be sent as the request body
  // Only applicable for request methods 'PUT', 'POST', 'DELETE , and 'PATCH'
  // When no `transformRequest` is set, must be of one of the following types:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer
  data: {
    firstName: 'Fred'
  },

  // syntax alternative to send data into the body
  // method post
  // only the value is sent, not the key
  data: 'Country=Brasil&City=Belo Horizonte',

  // `timeout` specifies the number of milliseconds before the request times out.
  // If the request takes longer than `timeout`, the request will be aborted.
  timeout: 1000, // default is `10000`

  // `withCredentials` indicates whether or not cross-site Access-Control requests
  // should be made using credentials
  withCredentials: false, // default

  // `adapter` allows custom handling of requests which makes testing easier.
  // Return a promise and supply a valid response (see lib/adapters/README.md).
  adapter: function (config) {
    /* ... */
  },

  // `responseType` indicates the type of data that the server will respond with
  // options are: 'arraybuffer', 'document', 'json', 'text', 'stream'
  //   browser only: 'blob'
  responseType: 'json', // default

  // `xsrfCookieName` is the name of the cookie to use as a value for xsrf token
  xsrfCookieName: 'XSRF-TOKEN', // default

  // `xsrfHeaderName` is the name of the http header that carries the xsrf token value
  xsrfHeaderName: 'X-XSRF-TOKEN', // default

  // `validateStatus` defines whether to resolve or reject the promise for a given
  // HTTP response status code. If `validateStatus` returns `true` (or is set to `null`
  // or `undefined`), the promise will be resolved; otherwise, the promise will be
  // rejected.
  validateStatus: function (status) {
    return status >= 200 && status < 300; // default
  },

  // `cancelToken` specifies a cancel token that can be used to cancel the request
  // (see Cancellation section below for details)
  cancelToken: new CancelToken(function (cancel) {
  }),
}

Response Schema

响应数据包含的内容：

{
  // `data` is the response that was provided by the server
  data: {},

  // `status` is the HTTP status code from the server response
  status: 200,

  // `headers` the HTTP headers that the server responded with
  // All header names are lower cased and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `appletsRequest` for the request
  config: {},

  // `originalRes` 是不同小程序request接口success中原始的返回值
  originalRes: {}
}

When using then, you will receive the response as follows:

appletsRequest.get("/user/12345").then(function (response) {
  console.log(response.data);
  console.log(response.status);
  console.log(response.headers);
  console.log(response.config);
  console.log(response.originalRes);
});

Handling Errors

Error Schema

catch或reject中的错误数据

{
  // `errMsg` String
  errMsg: "Network Error",

  // `status` is the HTTP status code from the server response
  // 或者值为`NETWORK_ERROR`和`TIMEOUT`
  status: 500,

  // 小程序接口返回的响应数据信息
  response: {},

  // `config` is the config that was provided to `appletsRequest` for the request
  config: {},

  // `extra` adapter开发者自定义数据，默认为`fail(err)`中返回的`err`
  extra: {}
}

appletsRequest.get("/user/12345").catch(function (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.log(error.response.data);
    console.log(error.response.status);
    console.log(error.response.headers);
  } else {
    // Something happened in setting up the request that triggered an Error
    console.log("Error", error.errMsg);
  }
  console.log(error.config);
});

Config Defaults

修改默认配置，将会在当前的appletsRequest实例中的所有请求生效，defaults中的配置优先级最低。

appletsRequest.defaults.baseURL = "https://api.example.com";
appletsRequest.defaults.headers.common["Authorization"] = AUTH_TOKEN;
appletsRequest.defaults.headers.post["Content-Type"] =
  "application/x-www-form-urlencoded";

Create New Instance

// Set config defaults when creating the instance
const instance = appletsRequest.create({
  baseURL: "https://api.example.com",
});

// Alter defaults after instance has been created
instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;

Override Defaults

defaults中的配置优先级最低，单个请求的config将会覆盖defaults中的值

// Create an instance using the config defaults provided by the library
// At this point the timeout config value is `0` as is the default for the library
const instance = appletsRequest.create();

// Override timeout default for the library
// Now all requests using this instance will wait 2.5 seconds before timing out
instance.defaults.timeout = 2500;

// Override timeout for this request as it's known to take a long time
instance.get("/longRequest", {
  timeout: 5000,
});

Interceptors

You can intercept requests or responses before they are handled by then or catch.

// Add a request interceptor
appletsRequest.interceptors.request.use(
  function (config) {
    // Do something before request is sent
    return config;
  },
  function (error) {
    // Do something with request error
    return Promise.reject(error);
  },
);

// Add a response interceptor
appletsRequest.interceptors.response.use(
  function (response) {
    // Any status code that lie within the range of 2xx cause this function to trigger
    // Do something with response data
    return response;
  },
  function (error) {
    // Any status codes that falls outside the range of 2xx cause this function to trigger
    // Do something with response error
    return Promise.reject(error);
  },
);

If you need to remove an interceptor later you can.

const myInterceptor = appletsRequest.interceptors.request.use(function () {
  /*...*/
});
appletsRequest.interceptors.request.eject(myInterceptor);

You can add interceptors to a custom instance of appletsRequest.

const instance = appletsRequest.create();
instance.interceptors.request.use(function () {
  /*...*/
});

Cancellation

You can cancel a request using a cancel token.

The appletsRequest cancel token API is based on the withdrawn cancelable promises proposal.

You can create a cancel token using the CancelToken.source factory as shown below:

const CancelToken = appletsRequest.CancelToken;
const source = CancelToken.source();

appletsRequest
  .get("/user/12345", {
    cancelToken: source.token,
  })
  .catch(function (thrown) {
    if (appletsRequest.isCancel(thrown)) {
      console.log("Request canceled", thrown.message);
    } else {
      // handle error
    }
  });

appletsRequest.post(
  "/user/12345",
  {
    name: "new name",
  },
  {
    cancelToken: source.token,
  },
);

// cancel the request (the message parameter is optional)
source.cancel("Operation canceled by the user.");

You can create a cancel token using new CancelToken as shown below:

const cancelToken = new appletsRequest.CancelToken();

appletsRequest
  .get("/user/12345", {
    cancelToken: cancelToken,
  })
  .catch(function (thrown) {
    if (appletsRequest.isCancel(thrown)) {
      console.log("Request canceled", thrown.message);
    } else {
      // handle error
    }
  });

// cancel the request (the message parameter is optional)
cancelToken.cancel("Operation canceled by the user.");

You can also create a cancel token by passing an executor function to the CancelToken constructor:

const CancelToken = appletsRequest.CancelToken;
let cancel;

appletsRequest.get("/user/12345", {
  cancelToken: new CancelToken(function executor(c) {
    // An executor function receives a cancel function as a parameter
    cancel = c;
  }),
});

// cancel the request
cancel();

Note: you can cancel several requests with the same cancel token. Note: 同一 cancelToken 只能使用一次，也就是执行了cancelToken.cancel(message),cancelToken就处于cancel状态。需要重新创建cancelToken对象

实现Adapter

未完待续

License

MIT