ryoko

ryoko，一个基于浏览器原生Fetch API的HTTP请求库。

特性

• 简易API设计
• 全局响应和请求拦截器
• 局部钩子：beforeRequest、afterResponse
• 延迟和手动终止一个或多个请求
• 下载进度监听
• URL前缀、Status验证
• 快捷操作语法，如：ryoko.post()
• 完善的错误提示

安装

使用npm：

npm install ryoko -S

使用cdn：

//unpkg
<script src="https://unpkg.com/ryoko/dist/ryoko.min.js"></script>

//jsdelivr
<script src="https://cdn.jsdelivr.net/npm/ryoko/dist/ryoko.min.js"></script>

API

ryoko(config)

通过传入config配置选项来新建一个ryoko请求

import ryoko from 'ryoko';

ryoko({
	method: 'post',
	url: '/guoxiaoyou/lalaal',
	data: {
		name: 'haha',
		age: 13,
	}
}).then(res => {
	console.info(res.data)
})

或者使用别名，如：

ryoko.get(url, config?)

ryoko.post(url, config?)

ryoko.put(url, config?)

ryoko.patch(url, config?)

ryoko.delete(url, config?)

ryoko.head(url, config?)

config配置详情：

{
	//请求方法，默认为get
	method: 'post',
	
	//请求的url
	url: '/guoxiaoyou',
	
	//prefixUrl，请求url的前缀，默认：''空字符串
	prefixUrl: 'https://www.guoxiaoyou.cn',
	
	//url查询参数，类型：String | PlainObject纯对象 | URLSearchParams
	params: {
		name: 'guoxiaoyou'.
		age: '10'
	},
	
	//headers为自定义请求头，类型：Headers | Record<string,string>
	headers: {
		'Content-Type': 'application/x-www-form-urlencoded'
	},
	
	//data请求体，用于fetch.body选项，类型：BodyInit
	//若为PlainObject纯对象，如{a:2,b:3}，内部将使用JSON.stringify转译
	data: new URLSearchParams(),
	
	//超时时间，默认0，即不取消请求
	timeout: 10000,
	
	//超时后触发的函数，参数：超时取消信息
	onDefer(deferMsg){
		
	},
	
	//下载进度监听
	downloadScheduler({
		percent, //百分百
		total, //总长度（字节）
		received, //当前得到的长度
		buffer, //所得资源二进制数据
	}) {
		
	}
	
	//响应状态码验证
	verifyStatus(status) {
		return status > 200
	},
	
	//请求前钩子
	beforeRequest(config) {
		
	},
	
	//响应后钩子
	afterResponse(response) {
	
	},
	
	//终止请求令牌
	abortToken,
	
	//是否自动携带上cookie，默认'same-origin‘（同源情况下），其它可选值：'omit'、'include'
	//特别的，为true时，即表示'include'，false对应'omit'
	credentials: true,
	
	//响应数据类型，默认：'text'，其它可选值：'arrayBuffer' | 'text' | 'json' | 'formData' | 'blob'
	responseType: 'json',
	
	//自定义fetch函数，如引入的polyfill
	fetch: fetchPolyfill
	
}

除此之外还继承了fetch请求原生的mode、integrity、redirect、cache、referrer、referrerPolicy等配置选项。详见（MDN之fetch API文档参考）

ryoko静态方法或属性

• ryoko.AbortTokenizer：终止ryoko请求的令牌控制器

• ryoko.create：创建一个新的请求实例

• ryoko.all：并发处理（等待多个）ryoko请求，基于Promise.all实现

• ryoko.spread：可在处理完并发请求后调用，如：

  const req = ryoko.get('/ddd')
  const req2 = ryoko.get('/ccc')
    
  ryoko.all(req, req2).then(ryoko.spread((res1, res2) => {
  	//res1、res2分别对应第一、二个请求的响应结果
  }))

• ryoko.Ryoko：即ryoko请求对象的原始构造类

创建ryoko实例

使用ryoko.create方法即可创建新的请求实例，一般还会传递一些默认参数，如timeout、prefixURL等。

const anfrage = ryoko.create({
	timeout: 1000,
	prefixURL: 'https://www.guoxiaoyou.cn'
})
anfrage.defaults.onDefer = function() { 
	console.info('请求超时了')
}

注意，若后续请求中具有相同配置，则遵循后入为主原则。如：

anfrage.get('/ddd', {
	timeout: 800
})

此时timeout为800毫秒。

拦截器

在正式请求前或响应后砸门往往需要处理某些工作，如给请求头加上token、loading动画加载等，拦截器则能很好地满足需求。如：

//请求拦截器
ryoko.interceptors.request.use((config) => {
	config.headers['Authorization'] = localStorage.getItem('token');
	return config;
},(err) => {
	return Promise.reject(err)
})

//响应拦截器
ryoko.interceptors.response.use(function(response) {
	return response
}, (err) => {
	return Promise.reject(err)
})

如果需要移除拦截器，可使用：

const inter = ryoko.interceptors.response.use((res) => {
	return res
})
ryoko.interceptors.response.eject(inter);

特别的，需要注意拦截器与局部钩子beforeRequest、afterResponse的差异。比如说：

1、执行顺序上：全局request拦截器 > 局部beforeRequest钩子 > 局部afterResponse钩子 > 全局response拦截器

//请求拦截器
ryoko.interceptors.request.use((config) => {
	console.info(1)
	return config;
})

//响应拦截器
ryoko.interceptors.response.use(function(response) {
	console.info(4)
	return response
})

ryoko.get({
	beforeRequest(config) {
		console.info(2)
	},
	afterResponse(response) {
		console.info(3)
	}
})

//执行后依次打印：1、2、3、4

2、全局拦截器必须将config或response参数返回，局部的beforeRequest、afterResponse钩子则不作要求；

下载进度监听

前文已经提及，在配置选项中加入downloadSchduler即可监听下载进度。如：

ryoko.get('/ddd', {
	downloadSchduler({percent, received, total, buffer}) {
		
	}
})

该方法接受一个形参：downloadInfo下载信息，该参数又包含四个属性：

• percent：下载进度百分比
• received：实时获取的字节长度
• total：总字节长度
• buffer：获取到的资源数据（Uint8Array类型）

注意点：此方法基于请求响应头的Content-length实现（因为fetch并未提供类似XHR的原生下载进度监测事件），所以对于没有Content-Type响应头参数的会无效。

ryokoResponse响应数据

{
	//请求配置，类型：ryokoMergeConfig
	config,
	
	//headers响应头，类型：PlainObject纯对象
	headers,
	
	//响应状态码
	status,
	
	//响应状态内容
	statusText,
	
	//fetch请求返回值
	source,
	
	//被处理后的fetch请求返回值，如res.json()
	data
}

注意，data是根据传入的responseType才被处理后的响应数据，而source选项才是真正的fetch请求后的返回值。

取消请求控制

第一种是设置timeout，若请求超时，则自动终止，同时触发onDefer回调。此外，用户也可手动取消。如：

import ryoko, { abortPendingRequest } from 'ryoko'

//获取请求终止令牌器
const AbortTokenizer = ryoko.AbortTokenizer;

// 创建一个终止令牌
const creatorToken = AbortTokenizer.createToken();

//再讲令牌token赋值给请求
ryoko.get('/ddd', {
	abortToken: creatorToken
})

//延迟120毫秒取消请求（如果该请求未完成）
setTimeout(() => {
	abortPendingRequest(creatorToken)
}, 120)

上述代码可以看到，取消一个请求需经过三个步骤：首先拿到终止控制器（AbortTokenizer），然后通过createToken方法创建终止令牌标识（一个Symbol值），它需赋予请求的abortToken选项，后续借助调abortPendingRequest方法便可取消对应请求。

同样，该方法适用于取消多个请求场景。如：

写法一：abortToken添加在基础配置选项上

const AbortTokenizer = ryoko.AbortTokenizer;
const creatorToken = AbortTokenizer.createToken();

let afrange = ryoko.create({
	abortToken: creatorToken
})

anfrage.get('/ddd', {
	params: {
		age: 10
	}
})

anfrage({
	method: 'post',
	url: '/sss',
	data: JSON.strigify({a:1,b:2})
})

//此时两个请求都将被取消（如果还没请求完成）
setTimeout(() => {
	abortPendingRequest(createToken)
}, 20)

写法二：逐个添加abortToken

const AbortTokenizer = ryoko.AbortTokenizer;
const creatorToken = AbortTokenizer.createToken();
 
ryoko.get('/ddd', {
	params: {
		age: 10
	},
	abortToken: creatorToken
})

ryoko({
	method: 'post',
	url: '/sss',
	data: JSON.strigify({a:1,b:2}),
	abortToken: creatorToken
})

//此时两个请求都将被取消（如果还没请求完成）
setTimeout(() => {
	abortPendingRequest(createToken)
}, 20)

关于运行环境

ryoko提供fetch选项方便用户使用自定义fetch方法。如对于在2015年之前发布的、不支持fetch的浏览器，可引入whatwg-fetch、node环境也可依托node-fetch。

//在老版浏览器
import {fetch as fetchPolyfill} from 'whatwg-fetch';

ryoko({
	url: 'ddd',
	fetch: fetchPolyfill
})

//在node环境
const fetchNode = require('node-fetch');
ryoko.get('/ddd', {
	fetch: fetchNode
})

作者

果小右——gejiuyuan.gitee.io😊