@lichao.franklee/ajax v1.0.1
@lx-frontend/ajax
一个规范Ajax使用的框架
安装
使用npm:
npm install @lx-frontend/ajax
使用yarn:
yarn add @lx-frontend/ajax
浏览器全局引入:
将dist/index.min.js文件复制到项目中,在html中引入脚本。
<script src="/path/to/index.min.js"></script>
该脚本暴露了Ajax类,使用时还需进一步实例化。
Example
// 请求库实例
import axios from 'axios';
import Ajax from '@lx-frontend/ajax';
// rest配置
const rest = {
firstModule: {
getCall: ['get', '/the/request/url', requestOptions],
postCall: ['post', '/the/post/url', requestOptions]
}
}
// 实例化配置
const options = {
rest,
requestInstance: axios
}
// 实例化
const ajax = new Ajax(options)
完成Ajax实例化之后,即可使用如下方式发起请求:
ajax.$rest.firstModule.getCall().then(res => {/***/})
ajax.$rest.firstModule.postCall(data).then(res => {/***/})
options配置
// const ajax = new Ajax(options)
{
requestInstance
rest
baseUrl
extension
isProduction
requestInterceptor
responseOkInterceptor
responseErrorInterceptor
responseNotOkHandler
errorReporter
schema
handleRequestDataInvalid
handleResponseDataInvalid
}
requestInstance
请求库的实例,目前支持axios和flyio。
注意这里传入的是请求库的实例对象,而不是类。请求库在不同的场景下有不同的实例化方式,具体请参考axios和flyio文档。
rest
该框架要求所有请求必须属于一个模块,rest对象的每个属性则代表一个模块,模块下是具体的请求函数配置。
rest的配置遵循如下模式:
{
moduleName: {
funcName: [method, url, requestOptions]
// ...
}
// ...
}
例如:
如下rest配置中,firstModule
是模块名称,该模块下有两个名为getCall
和postCall
的请求
const rest = {
firstModule: {
getCall: ['get', '/the/request/url'],
postCall: ['post', '/the/post/url']
}
}
rest的结构决定了Ajax在实例化之后的调用方式,比如,getCall
和postCall
将通过如下方式调用:
// const ajax = new Ajax(options)
// 实例化之后,请求函数组成的模块将被挂载到 $rest 属性下
ajax.$rest.firstModule.getCall().then(/***/)
ajax.$rest.firstModule.postCall().then(/***/)
请求配置 method, url, requestOptions
模块下具体的请求通过一个三元数组配置而来,数组项分别表示:请求的方法,请求的路径,以及对请求的配置。
method: string类型,目前仅支持get, put, post, patch, delete方法
url: string类型,该路径将和requestOptions的baseUrl属性拼接,组成最终的请求路径。
requestOptions: object, 详见requestOptions
requestOptions
{
isReturnRes // Boolean,true表示直接返回response,false表示返回response.data
baseUrl // 请求路径前缀,拼接在url之前,构成一个完整的请求路径
cache // Boolean,该请求是否开启缓存,可选,默认false
dataType // json/form, POST、DELETE、PATCH、PUT请求提交数据的格式(JSON或者FromData)
// ...
}
isReturnRes: boolean
default: false
请求完成后,是否返回完整的response对象给业务代码处理。
默认false,表示请求完成后,会获取response的data属性,然后将data返回给业务逻辑。
baseUrl: string
default: ''
请求路径前缀,baseUrl + url共同构成请求的完整路径。
Ajax实例化参数中也有该属性,具体请求上的baseUrl优先级更高,会替换Ajax实例化参数中的同名参数。
dataType: json/form
default: 'json'
post,put,patch,delete请求携带数据的格式。
支持两个值:'json' 和 'form'。json表示JSON格式,form表示FormData格式
cache: Boolean
default: false
表示请求是否开启浏览器缓存,默认不开启。
其他参数
requestOptions最终会合并到请求的配置中去,所以,只要是请求库支持的请求配置都可以在这里配置。
baseUrl
请求路径前缀,string类型,该值会和每个请求的url配置合并,构成最终的请求路径。
requestOptions中的baseUrl会覆盖该配置。
extension
用于扩展Ajax实例,该配置下的所有属性都会在Ajax实例化后,挂载到实例对象上。
若Ajax实例化完成后,仍想扩展实例,可以使用实例的extend方法:
// const ajax = new Ajax(options);
ajax.extend({/***/})
isProduction: Boolean or Function
判断当前环境是否是生产环境,用作功能开关,比如信息打印。
requestInterceptor: response => response
请求拦截器处理函数,(config) => config,可选。
对于不同的请求库(axios/flyio),这里的config会有一些差异,具体请查阅请求库文档。
注意:不要使用箭头函数,函数执行上下文(this)指向ajax实例。
responseOkInterceptor: response => response
响应成功拦截器处理函数,response => response, 可选。
注意:不要使用箭头函数,函数执行上下文(this)指向ajax实例。
responseErrorInterceptor: err => any
响应请求错误的拦截器,即status不等于304且不在[200, 300),error => any,可选。
若函数返回Promise.reject(err),错误将由catch捕获,并将错误交给errorReporter处理,最后err也将透传给业务逻辑(注意,业务代码中使用then的成功处理函数接收该值,而不是catch或then的失败处理函数,所以业务逻辑中要判断返回值是否符合要求)。
若函数返回一个值(err),框架根据请求的isReturnRes配置,返回err或者err.data给业务逻辑。如果err.data不存在,则返回undefined。
注意:不要使用箭头函数,函数执行上下文(this)指向ajax实例。
responseNotOkHandler: response => void
请求正常返回,但后端判断请求出错,即status===200 && res.data.code!==0,可选。
这里可以通知用户错误信息,或做其他处理。
errorReporter: err => void
用于上报错误信息,比如上报sentry等。可选。
schema
用于存放请求数据和返回数据校验所需的JSONSchema,配置结构和rest的结构一致。
比如,假如rest的配置如下:
{
moduleName: {
funcName: [method, url, requestOptions]
// ...
}
// ...
}
则,如果要校验funcName请求的数据,其配置如下:
{
moduleName: {
funcName: {
requestSchema: /* request data Jsonschema */,
responseSchema: /* response data Jsonschema */
}
// ...
}
// ...
}
其中,区别在于,原函数的数组配置项被Jsonschema配置替换。requestSchema和responseSchema是固定属性名,可以不配置,默认通过校验。
handleRequestDataInvalid: (url, message) => void
请求参数校验失败时的处理函数。用户可以决定当请求参数校验失败时做些什么。可选,默认打印两个参数。
函数的第一个参数为请求的url路径,第二个参数是错误信息。
handleResponseDataInvalid: (url, message) => void
返回数据校验未通过时的处理函数。用户自定义,可选,默认打印两个参数。
TODO:如果handleRequestDataInvalid和handleResponseDataInvalid抛出错误,会有什么影响?要怎么处理?
待实现想法:
下一步方向: 1. 兼容wx原生请求 2. 自动生成jsonschema 3. 仅返回最后一次请求的数据
4 years ago