README
legions-request
Promise based HTTP client for the browser and node.js
what is legions-request?
legions-request 是一个支持浏览器及服务端的 http 请求工具库
Features
- 高版本浏览器直接基于 fetch
- 低版本不支持 fetch 时，自动降级兼容 fetch 所有特性
- nodejs 中通过 http 发送请求
- Supports the Promise API
- 支持注入 request,respone,reject 等拦截器
- 超时自动中断请求
Installing
Using npm and yarn :
npm i legions-requset -S
or
yarn add legions-requset -S
Using jsDelivr CDN:
<script src="dist/index.iife.js"></script>
Example
import { get, post } from 'lesgions-request';
get({
url: '/user?ID=12345',
}).then(function (response) {
// handle success
console.log(response);
});
POST Requests
How to perfrom POST requests with legions-request
Performing a POST request
import { get, post } from 'lesgions-request';
post({
url: '/user',
data: {
firstName: 'Fred',
lastName: 'Flintstone',
},
}).then(function (response) {
console.log(response);
});
Performing multiple concurrent requests
function getUserAccount() {
return get({
url: '/user/12345',
});
}
function getUserPermissions() {
return get({
url: '/user/12345/permissions',
});
}
Promise.all([getUserAccount(), getUserPermissions()]).then(function (results) {
const acct = results[0];
const perm = results[1];
});
legions-request api
The legions-request API Reference
legionFetch.instance.request(config)
// Send a POST request
legionFetch.instance.request({
method: 'post',
url: '/user/12345',
data: {
firstName: 'Fred',
lastName: 'Flintstone',
},
});
// GET request for remote image in node.js
legionFetch.instance
.request({
method: 'get',
url: 'http://bit.ly/2mTM3nY',
responseType: 'stream',
})
.then(function (response) {
response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'));
});
Request method aliases
For convenience aliases have been provided for all supported request methods.
- legionFetch.instance.request({method: 'get'})
- legionFetch.instance.request({method: 'delete'})
- legionFetch.instance.request({method: 'head'})
- legionFetch.instance.request({method: 'options'})
- legionFetch.instance.request({method: 'post'})
- legionFetch.instance.request({method: 'put'})
- legionFetch.instance.request({method: 'patch'})
- legionFetch.instance.get(config)
- legionFetch.instance.post(config)
The legions-request Instance
Creating an instance
You can create a new instance of axios with a custom config.
import { legionFetch } from 'lesgions-request';
const instance = legionFetch.create();
Instance methods
- instance.request({method: 'get'})
- instance.request({method: 'delete'})
- instance.request({method: 'head'})
- instance.request({method: 'options'})
- instance.request({method: 'post'})
- instance.request({method: 'put'})
- instance.request({method: 'patch'})
- instance.get(config)
- instance.post(config)
Request Config
These are the available config options for making requests. Only the url is required. Requests will default to GET if method is not specified.
{
// `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 axios to pass relative URLs
// to methods of that instance.
baseURL: 'https://some-domain.com/api/',
// 发送前对配置数据进行处理
transformRequest: function (config, url) {
// Do whatever you want to transform the data
return config;
},
// `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
// NOTE: params that are null or undefined are not rendered in the URL.
params: {
ID: 12345
},
// `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 `0` (no timeout)
// should be made using credentials
// "include" | "omit" | "same-origin"
credentials: 'include', // default
// `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
// `maxRedirects` defines the maximum number of redirects to follow in node.js.
// If set to 0, no redirects will be followed.
maxRedirects: 5, // default
// data 数据是否默认转json，默认true,只有在data是对象时才会执行
isDataToConvertJson:boolean,
/**
* A cryptographic hash of the resource to be fetched by request. Sets request's integrity.
*/
integrity?: string,
/**
* A boolean to set request's keepalive.
*/
keepalive?: boolean,
/**
* A string to set request's method.
*/
method?: string,
/**
* A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode.
*/
mode?: RequestMode,
/**
* A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.
*/
redirect?: RequestRedirect,
/**
* A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer.
*/
referrer?: string,
/**
* A referrer policy to set request's referrerPolicy.
*/
referrerPolicy?: ReferrerPolicy,
/**
* An AbortSignal to set request's signal.
*/
signal?: AbortSignal | null,
}
拦截器
在请求或响应被 then 处理前拦截它们。
use
legionFetch.instance.register({
request: (config) => {
config.credentials = 'omit';
return config;
},
response: (res) => {
return res;
},
responseReject: (res) => {
return res;
},
});
默认注入的拦截器
request
const defaultRequest = [
{
request: (configs /** 传入进来的配置参数*/) => {
//注册拦截请求, 默认所有请求返回json格式
/** 设置默认request */
let options = {
headers: {
'content-type': 'application/json',
},
credentials: 'include',
};
/** 使用传入进来的配置覆盖默认配置*/
let config = mergeConfig(options, { ...tranfromOptions(configs.options), url: configs.url });
return config;
},
},
{
request: (configs: IRequestConfigs) => {
//注册请求, 请求默认携带验证参数
let options = {
/** 超时时间*/
timeout: 50000,
};
let config = mergeConfig(options, configs);
return config;
},
},
];
response
defaultResponse = [
{
response: (response, config: IRequestConfigs) => {
return response;
},
},
{
//response已经被反序列化, 返回了对应对象
response: (response, config: IRequestConfigs) => {
if (config && config.responseType === 'json') {
const res = response.json();
return res;
}
return response;
},
},
];
Reject
[
{
//@ts-ignore
responseReject: (response, config) => {
let error: any = {};
if (response instanceof FetchError) {
error = {
name: response.name,
type: response.type,
code: response.code,
message: response.message,
};
} else if (response instanceof Error) {
error = {
name: response.name,
type: response.name,
stack: response.stack,
message: response.message,
};
}
return Promise.resolve(
new ResponseResult({
success: false,
message: JSON.stringify(error),
code: error.type === 'request-timeout' ? DataRequestStateEnum.Timeout.toString() : '500',
data: null,
}),
);
},
},
];