version/0.X.md · @xyzi/request

# request 0.X

request为uni-app的vue3项目、web的vue3项目中的常规请求插件。API为
组合式API风格，支持全局/局部请求前置/后置拦截。其中浏览器兼容性同步vue3，
默认使用uni.request(defineRequest中可另行声明)。

[文档地址](https://gitee.com/xy_zi/request)

## 入门
### 引入

```sh
npm install @xyzi/request
```

* main.js

```js
import {defineRequest} from '@xyzi/request'
defineRequest()
```

### 简单使用

* .vue

```html
<script setup>
	import {useRequest} from '@xyzi/request'
	const {
		getState,    //请求参数,其中res为响应结果
		getRequest,  //请求方法
		getIntercept,//请求追踪方法
		getInit,     //请求参数初始化方法
		getExpose,   //暴露到当前对象this上
		getTask,     //请求对象
	} = useRequest({ //参数同步uni.request参数
		url: "/",
		data: {}
	})
 </script>
```

### 执行周期

* 请求正常

```
全局xxxBefore --> 页面before    --> 发送请求
页面after     --> 全局xxxAfter  --> 赋值res   -->
页面finish    --> 全局xxxFinish
```

* 请求异常

```
请求异常  --> 页面finish --> 全局xxxFinish
```

### 拦截说明

请配合使用以下API

* uniapp中的

```js
uni.addInterceptor("request", {
	invoke(args) {},
	success(){}
})
```

* axios中的

```js
const instance = axios.create({})
instance.interceptors.request.use(args => {})
instance.interceptors.response.use(args => {})
```

# API
## defineRequest
### 请求参数
#### 默认

默认使用uni.request方法

```js
import {defineRequest} from '@xyzi/request'
defineRequest()
```

#### axios

instance声明请参考 [拦截说明](#拦截说明)

```js
defineRequest(function (args) {
    return instance(args).then(args.success).catch(args.fail)
})
```

#### 其他

请使用异步函数作为主函数

### intercept

全局拦截

```js
const {intercept} = defineRequest()
```

#### 拦截方式

* [key关键字](#key)+Before/After/Finish
* key为需要拦截的请求的关键字
* Before请求前，After请求后，Finish请求完成

```js
intercept('xxxBefore',function(){})
intercept('xxxAfter',function(){})
intercept('xxxFinish',function(){})
```

#### 拦截方法
##### Before请求前

* 参数为调用[xxxRequest](#xxxRequest)时的参数

```js
// useRequest
xxxRequest(true)
// defineRequest
intercept('xxxBefore',function(args){
	console.log(args)  // true 
})
```

* 返回异步函数

```js
intercept('xxxBefore',function(){
	return new Promise((resolve,reject){})
})
```

* 返回异步错误则终止请求，如Promise.reject()

```js
intercept('xxxBefore',function(){
	return Promise.reject('error')
})
```

* 返回非异常值则作为下个周期的参数

```js
intercept('xxxBefore',function(){
	return true
})
```

* 作用域为当前useRequest对象

```js
intercept('xxxBefore',function(){
	/**
	 * xxxState,
	 * xxxRequest,
	 * xxxInit,
	 * ...
	 */
	console.log(this)
})
```

#### 拦截取消

```js
const cancel = intercept('xxxBefore',function(args){})
cancel()
```

## useRequest
### 请求参数

* 请求参数中，默认有key作为关键字，其值默认为get，
* 其他参数同步主函数参数，如uni.request或axios的请求参数

#### key

* 默认get

```js
const {
	getState,
	getRequest,
	getIntercept,
	getInit,
	getExpose,
	getTask,
	getEmit,
} = useRequest({
	url: '/'
})
```

* 自定义

```js
const {
	xxxState,
	xxxRequest,
	xxxIntercept,
	xxxInit,
	xxxExpose,
	xxxTask,
} = useRequest({
	key: 'xxx',
	url: '/'
})
```

#### loading

是否请求中

```js
useRequest({
	loading: false
})
```

#### res

响应结果

```js
useRequest({
	res: []
})
```

#### 其他参数

其他参数同主函数参数，如uni.request或axios

```js
useRequest({
	url: "/",
	method: 'POST',
	header: {}
})
```

### 扩展参数
#### proxy

xxxState响应方式，默认为reactive
参考[语法糖](#语法糖)

```js
useRequest({})                 //深代理
useRequest({},{proxy:'shallowReactive'}) //浅代理
useRequest({},{proxy:'toRaw'}) //不代理
```

#### fresh

是否缓存拦截，默认缓存拦截

```js
useRequest({})               //缓存
useRequest({},{fresh:false}) //不缓存
```

#### on

请求发布，[xxxEmit](#xxxEmit)请求订阅

```js
useRequest({},{on:'get'}) // 'get'为发布名
```

#### auto

是否自动执行

* auto的值为[xxxRequest](#xxxRequest)函数的参数
* 在onMounted钩子执行[xxxRequest](#xxxRequest)函数

### xxxState

请求参数响应值

* loading : 是否请求中
* res     : 响应结果
* 其他为定义时设置的参数

### xxxRequest

* 请求方法，用于启动整个拦截请求
* 请求携带的参数会传递到全局xxxBefore的拦截函数的参数中

### xxxTask

请求对象

### xxxIntercept

局部拦截

* before请求前，after请求后，finish请求完成
* 其他同全局[拦截方法](#拦截方法)

```js
xxxIntercept('before' ,function(){})
xxxIntercept('after' ,function(){})
xxxIntercept('finish' ,function(){})
```

### xxxInit

初始化xxxState

```js
xxxInit()
```

### xxxEmit

请求订阅，[on](#on)请求发布

```js
xxxEmit('get',args) //get为订阅名，args为参数
```

### xxxExpose

暴露到当前对象this上

```js
xxxExpose({})
```

### 语法糖
#### useRequestShallow

浅代理

```js
useRequest({},{proxy:'shallowReactive'})
```

#### useRequestRaw

不代理

```js
useRequest({},{proxy:'toRaw'})
```

#### useRequestFresh

不缓存拦截

```js
useRequest({},{fresh:false})
```

## defineUpload

* 默认方法为uni.uploadFile，默认key为upload
* 其他同[defineRequest](#definerequest)

## useUpload

* 同[useRequest](#userequest)

## defineDownload

* 默认方法为uni.downloadFile，默认key为download
* 其他同[defineRequest](#definerequest)

## useDownload

* 同[useRequest](#userequest)

@xyzi/request

简介

发行版

贡献者

近期动态

@xyzi/request .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

@xyzi/request