bxf(browser xhr and fetch)

bxf 是一款针对浏览器封装的多功能请求库，封装了 XHR 和 Fetch，以实现对 HTTP 请求的无缝处理。它能智能适应不同的环境，自动识别并支持各种请求类型。除了常规的网页请求外，它还特别设计以与使用 manifest_version: 3 的浏览器扩展无缝集成。这确保在现代 Web 开发环境中实现完美兼容性和最佳性能

安装

Use npm:

npm i bxf -S

Use yarn:

yarn add bxf

Use unpkg CDN:

<script src="https://unpkg.com/bxf"></script>

Examples

Use es6 module:

import bxf from 'bxf';
bxf('/url').then(res => console.log(res));

Use commonJs:

const bxf = require('bxf');
bxf('/url').then(res => console.log(res));

Use link:

<script src="https://unpkg.com/bxf"></script>

<script>
  bxf('/url').then(res => console.log(res));
</script>

Create Instance

const http = bxf.create({
  baseUrl: 'https://www.xxx.com', // 如果url是完整地址(http|https开头)的则会忽略baseUrl
  method: 'post', // 默认请求 get
  requestType: 'query',// 默认query 可选参数有['query', 'json', 'form', 'formdata']
  // responseType: null, // 默认null走text但如果返回的文本是json字符串会自动转成json对象，可选参数有 ['arrayBuffer', 'blob', 'blobText', 'formData', 'text', 'json'], 注意如果指定了text则不会自动判断转换json
  charset: false, // 是否为content-type 加上编码，可选值{true: 'utf-8', false: '不添加', ...其他任意编码字符串}
  // engine: null, // 引擎可选值['xhr', 'fetch', 以及其他自定义的全局函数]不符合可选值则进入自动判断选择
  // beforeSend: null, // 发送前的函数回调，只有是函数才会调用其他参数会被忽略，并且如果在beforeSend返回false则不会再进行请求了
  toDataOnly: false, // 是否只返回响应结果，忽略配置响应头等
  // contentType: undefined,
  // xhr: (request, config) => {}, // 只有engine是xhr请求才会在请求过程中调用该函数，可用于添加未定义到的xhr事件(如：获取上传进度)
  // xhr或fetch的原生字段
  rawFields: {

  }
});

create创建出来的实例用法与bxf相同，只是对未传参数使用了创建实例时传进去的参数。

Request Methods

// bxf 也是一个函数，可以直接进行请求
bxf({
  url: '/',
  method: 'post',
  data: {id: 1},
  params: {
    title: 'tom',
  },
  headers: {}
});
// 除了直接请求，还可以传入第二个参数printConfig 打印请求配置值为boolean，默认false只执行请求，为true则不进行真实请求只打印处理后的配置
bxf({
  url: '/',
  method: 'post',
  data: {id: 1},
  params: {
    title: 'tom',
  },
  headers: {}
}, true);

get

// 如果提供了params，则会被解析为拼接到请求url上的URLSearchParams，就像GET方式传递参数一样。
bxf.get('/');
bxf.get('http://api', {params: {id: 5}}); // expect url: http://api?id=5 
bxf.get('/', {params: {id: 5}, timeout: 3000});

post

// 如果data是对象或者数组，或者字符串，不设置的话Content-Type会设置为application/x-www-form-urlencoded，并且data会转为urlencoded类型，其他Content-Type则由进行requestType 参数和data类型自动判断
bxf.post('/');
bxf.post('/', {id: 5});
bxf.post('/', null, {timeout: 3000}); // the request body will be empty

delete

// 参照get
bxf.delete('/', {responseType: 'json'});

options

// 参照get
bxf.options('/', {});

head

// 参照get
bxf.head('/', {});

patch

// 参数post
bxf.patch('/', {}, {});

put

// 参数post
bxf.put('/', {}, {});

config & 请求参数可选字段

baseUrl

将自动加在 url 前面，除非 url 是一个绝对 URL。它可以通过设置一个 baseURL 便于为 bxf 实例的方法传递相对 URL

url

用于请求的服务器 URL

method

method 是创建请求时使用的方法

headers

headers 是即将被发送的自定义请求头

params

get参数，会自动转换处理成query的get参数

// 字符串类型 => 最终请求地址 https://www.xxx.com/?id=1&page=1
bxf({
  url: 'https://www.xxx.com',
  params: 'id=1&page=1',
})
// 对象类型 => 最终请求地址 https://www.xxx.com/?id=1&page=1
bxf({
  url: 'https://www.xxx.com',
  params: {
    id: 1,
    page: 1,
  } 
})

// 数组类型 => 最终请求地址 https://www.xxx.com?a=1&b=2&c=3&d=4&e=5&f%5B%5D=1&f%5B%5D=2&f%5B%5D=3&g%5Ba%5D=1&g%5Bb%5D=2
bxf({
  url: 'https://www.xxx.com',
  params: [
      ['a', 1],
      {b: 2},
      {c: 3, d: 4},
      'e=5',
      ['f', [1,2,3]],
      ['g', {a: 1, b: 2}],
  ] 
})

注意如果method是['get', 'delete', 'head', 'options']时params未定义而data有值则data会被等价于params处于到url上

data

data参数除了支持params的几种传参类型外还支持formData和json字符串，但最终以什么方式提交则是配合requestType参数判断的

requestType

指定请求类型

responseType

指定响应类型，一般放空或null即可，放空则会自动判断。如果指定了具体类型但最终返回类型不一致那么会取不到值。支持参数值['arrayBuffer', 'blob', 'blobText', 'formData', 'text', 'json']

charset

是否在content-type类型后添加返回指定编码一般可忽略

xhr

可选函数，仅在请求引擎为xhr时有效，一般用于补充未定义的事件，如上传文件进度，注意如果函数有返回值，并且返回false,则会中断请求

beforeSend

可选函数，在发送请求前调用，并且如果该函数返回false,则会中止请求

timeout

设置超时，！！！注意该字段我作了判断处理，如果值小于301会被当作秒被乘以1000，如果需要设置301以内的毫秒需要自行除以1000，而大于301单位则是毫秒

rawFields

补充原生字段，如fetch请求时设置是否使用缓存

bxf({
  url: 'https://www.xxx.com',
  rawFields: {
    cache: "no-store"
  }
})

拦截器

拦截器简介 在请求或响应被 then 或 catch 处理前拦截它们。

添加拦截器

// 添加请求拦截器
bxf.interceptors.request.use(function (config) {
    // 在发送请求之前做些什么
    return config;
  }, function (error) {
    // 对请求错误做些什么
    return Promise.reject(error);
  });

// 添加响应拦截器
bxf.interceptors.response.use(function (response) {
    // 对响应数据做点什么
    return response;
  }, function (error) {
    // 对响应错误做点什么
    return Promise.reject(error);
  });

• 请求拦截器：它的作用是在请求发送前统一执行某些操作，比如在请求头中添加 token 字段。
• 响应拦截器：它的作用是在接收到服务器响应后统一执行某些操作，比如发现响应状态码为 401 时，自动跳转到登录页。

此外我们还可以删除某个拦截器

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

取消功能

取消请求需求分析 使用 cancel token 取消请求，可以使用 CancelToken.source 工厂方法创建 cancel token，像这样：

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

bxf.get('/user/12345', {
  cancelToken: source.token
}).catch(function(thrown) {
  if (bxf.isCancel(thrown)) {
    console.log('Request canceled', thrown.message);
  } else {
     // 处理错误
  }
});

bxf.post('/user/12345', {
  name: 'new name'
}, {
  cancelToken: source.token
})

// 取消请求（message 参数是可选的）
source.cancel('Operation canceled by the user.');

还可以通过传递一个 executor 函数到 CancelToken 的构造函数来创建 cancel token

const CancelToken = bxf.CancelToken;
let cancel;

bxf.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // executor 函数接收一个 cancel 函数作为参数
    cancel = c;
  })
});

// cancel the request
cancel();

其他一些使用案例

上传文件

• fetch上传文件

var fd = new FormData()
fd.append('img', '文件句柄')
bxf({
  url: 'https://www.xxx.com/uploads',
  method: 'post',
  data: fd,
  contentType: false, // 上传文件需要禁止contentType请求头
  engine: 'fetch'
})

• xhr上传并监听上传进度

var fd = new FormData()
fd.append('img', '文件句柄')
bxf({
  url: 'https://www.xxx.com/uploads',
  method: 'post',
  data: fd,
  contentType: false, // 上传文件需要禁止contentType请求头
  engine: 'xhr',
  xhr: (xhr, config) => {
    xhr.upload.onprogress=function(eve){
          if (eve.lengthComputable){
              console.log(eve.loaded/eve.total);
          }
      }
  }
})

版本升级备注

v1.0.7

• 修复默认参数 responseType ,原本默认设置了text会导致无法自动判断json,需要自动判断json需要设置为非可选参数
• 增加了 beforeSend 对于网页请求可能需求不大，添加这个主要是本人在开发浏览器扩展mv3时做动态请求头修改时需要获取最终请求的url，而补充的
• 增加了打印配置的选项直接在bxf(requestConfig, true),则不会进行真实请求，只返回处理的配置

v1.0.8

• 增加toDataOnly 字段，可以仅返回响应数据

v1.0.10

• 修复xhr 响应类型非字符串，读取responseText错误问题
• 超时timeout原本小于100的的会被处理为秒，修改为小于301就按秒处理（因为一般常见的可接受超时大于两分钟的还是比较常见）
• 修复create对象配置未被合并处理

其他未列出的请前往github看源码。。。