umi-request

English | 简体中文

umi-request

The network request library, based on fetch encapsulation, combines the features of fetch and axios to provide developers with a unified api call method, simplifying usage, and providing common functions such as caching, timeout, character encoding processing, and error handling.

Supported features

• url parameter is automatically serialized
• post data submission method is simplified
• response return processing simplification
• api timeout support
• api request cache support
• support for processing gbk
• request and response interceptor support like axios
• unified error handling
• middleware support
• cancel request support like axios
• make http request from node.js

umi-request vs fetch vs axios

Features umi-request fetch axios implementation Browser native support Browser native support XMLHttpRequest size 9k 4k (polyfill) 14k query simplification ✅ ❌ ✅ post simplification ✅ ❌ ❌ timeout ✅ ❌ ✅ cache ✅ ❌ ❌ error Check ✅ ❌ ❌ error Handling ✅ ❌ ✅ interceptor ✅ ❌ ✅ prefix ✅ ❌ ❌ suffix ✅ ❌ ❌ processing gbk ✅ ❌ ❌ middleware ✅ ❌ ❌ cancel request ✅ ❌ ✅

For more discussion, refer to Traditional Ajax is dead, Fetch eternal life If you have good suggestions and needs, please mention issue

TODO Welcome pr

• Test case coverage 85%+
• write a document
• CI integration
• release configuration
• typescript

Installation

npm install --save umi-request

Example

Performing a GET request

import request from 'umi-request';

request
  .get('/api/v1/xxx?id=1')
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

// use options.params
request
  .get('/api/v1/xxx', {
    params: {
      id: 1,
    },
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Performing a POST request

request
  .post('/api/v1/user', {
    data: {
      name: 'Mike',
    },
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

umi-request API

Requests can be made by passing relevant options to umi-request

umi-request(url[, options])

import request from 'umi-request';

request('/api/v1/xxx', {
  method: 'get',
  params: { id: 1 },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

request('/api/v1/user', {
  method: 'post',
  data: {
    name: 'Mike',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Request method aliases

For convenience umi-request have been provided for all supported methods.

request.get(url[, options])

request.post(url[, options])

request.delete(url[, options])

request.put(url[, options])

request.patch(url[, options])

request.head(url[, options])

request.options(url[, options])

Creating an instance

You can use extend({[options]}) to create a new instance of umi-request.

extend([options])

import { extend } from 'umi-request';

const request = extend({
  prefix: '/api/v1',
  timeout: 1000,
  headers: {
    'Content-Type': 'multipart/form-data',
  },
});

request
  .get('/user')
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Create an instance of umi-request in NodeJS enviroment

const umi = require('umi-request');
const extendRequest = umi.extend({ timeout: 10000 });

extendRequest('/api/user')
  .then(res => {
    console.log(res);
  })
  .catch(err => {
    console.log(err);
  });

The available instance methods are list below. The specified options will be merge with the instance options.

request.get(url[, options])

request.post(url[, options])

request.delete(url[, options])

request.put(url[, options])

request.patch(url[, options])

request.head(url[, options])

request.options(url[, options])

More umi-request cases can see antd-pro

request options

Parameter Description Type Optional Value Default method request method string get , post , put ... get params url request parameters object or URLSearchParams -- -- data Submitted data any -- -- headers fetch original parameters object -- {} timeout timeout, default millisecond, write with caution number -- timeoutMessage customize timeout error message, please config timeout first string -- -- prefix prefix, generally used to override the uniform settings prefix string -- -- suffix suffix, such as some scenes api need to be unified .json string -- credentials fetch request with cookies string -- credentials: 'same-origin' useCache Whether to use caching (only support browser environment) boolean -- false validateCache cache strategy function (url, options) => boolean -- only get request to cache ttl Cache duration, 0 is not expired number -- 60000 maxCache Maximum number of caches number -- 0(Infinity) requestType post request data type string json , form json parseResponse response processing simplification boolean -- true charset character set string utf8 , gbk utf8 responseType How to parse the returned data string json , text , blob , formData ... json , text throwErrIfParseFail throw error when JSON parse fail and responseType is 'json' boolean -- false getResponse Whether to get the source response, the result will wrap a layer boolean -- fasle errorHandler exception handling, or override unified exception handling function(error) -- cancelToken Token to cancel request CancelToken.token -- --

The other parameters of fetch are valid. See fetch documentation

extend options Initialize default parameters, support all of the above

Parameter Description Type Optional Value Default method request method string get , post , put ... get params url request parameters object -- -- data Submitted data any -- -- ...

…

Extend Options

Sometimes we need to update options after extend a request instance, umi-request provide extendOptions for users to update options:

const request = extend({ timeout: 1000, params: { a: '1' } });
// default options is: { timeout: 1000, params: { a: '1' }}

request.extendOptions({ timeout: 3000, params: { b: '2' } });
// after extendOptions: { timeout: 3000, params: { a: '1', b: '2' }}

Response Schema

The response for a request contains the following information.

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

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

  // 'statusText' is the HTTP status message from the server response
  statusText: 'OK',

  // 'headers' the headers that the server responded with
  // All header names are lower cased
  headers: {},
}

When options.getResponse === false, the response schema would be 'data'

request.get('/api/v1/xxx', { getResponse: false }).then(function(data) {
  console.log(data);
});

When options.getResponse === true ，the response schema would be { data, response }

request.get('/api/v1/xxx', { getResponse: true }).then(function({ data, response }) {
  console.log(data);
  console.log(response.status);
  console.log(response.statusText);
  console.log(response.headers);
});

You can get Response from error object in errorHandler or request.catch.

Error handling

…

Middleware

Expressive HTTP middleware framework for node.js. For development to enhance before and after request. Support create instance, global, core middlewares.

Instance Middleware (default) request.use(fn) Different instances's