@txjs/taro-request

写在前面

目前仅在微信小程序和支付宝小程序有线上使用，其他小程序有什么问题可以issues

该库是从miniprogram-network改造而来，在此表示感谢

API

支持方法:

• request<T>(options): Promise<T>;
• request<T>(method, action, data?, config?): Promise<T>;
• get<T>(action, data?, config?): Promise<T>;
• post<T>(action, data?, config?): Promise<T>;
• put<T>(action, data?, config?): Promise<T>;
• delete<T>(action, data?, config?): Promise<T>;
• patch<T>(action, data?, config?): Promise<T>;
• head<T>(action, data?, config?): Promise<T>;

支持配置

• url 地址 required (只能请求时设置for single request)
• method 方法 (只能请求时设置for single request)
• data 数据 (只能请求时设置for single request)
• cancelToken 取消 (只能请求时设置for single request)
• onHeadersReceived 接收头响应 (只能请求时设置for single request)
• timeout 自定义超时时间ms (只能请求时设置for single request)
• responseType 返回数据类型
• headers 请求头
• params URL参数
• baseURL 根URL
• retry 重试次数
• timestamp 是否记录发送和响应时间戳
• transformSend 输入转换函数
• transformResponse 输出转换函数

Listeners

• onSend (before request data send & after request data transformed)
• onResponse (after request response data transformed)
• onRejected (before catch of Promise)
• onAbort
• onComplete

npm安装

npm i @txjs/taro-request

quick start

1import { REQUEST } from '@txjs/taro-request'
2
3// 设置全局配置，设置一次全部生效
4// 设置请求根地址,可选
5REQUEST.Defaults.baseURL = 'https://api.example.com'
6
7// 添加监听时间 可选
8REQUEST.Listeners.onResponse.push(console.log)
9
10REQUEST.get('items')
11  .then()
12  .catch()

URL build

1// POST /items
2// {name:"future"}
3REQUEST.post('/items',{ name: 'future' })
4
5// GET /items/12345?show_detail=false
6REQUEST.get('/items/{id}', {
7  show_detail: false
8}, {
9  params: {
10    id: 12345
11  }
12})
13
14// PUT /items/12345
15// {name:"new"}
16// --- json 序列化body
17REQUEST.put('/items/{id}', {
18  name: 'new'
19}, {
20  params: {
21    id: 12345
22  }
23})
24
25// 由于小程序不支持Patch，此处使用X-HTTP-Method-Override实现Patch
26// 此功能需要服务器端支持
27// POST /items/12345
28// X-HTTP-Method-Override: PATCH
29// {name:"new"}
30REQUEST.patch('/items/{id}', {
31  name: 'new'
32}, {
33  params: {
34    id: 12345
35  }
36})

TypeScript

泛型支持

1// TS 类型推断
2import { REQUEST, transformRequestResponseOkData } from '@txjs/taro-request'
3
4// 自动提取返回值为 2xx 时的 `response.data`
5REQUEST.Defaults.transformResponse = transformRequestResponseOkData
6
7interface Item {
8  id: number
9  name: string
10}
11
12// 泛型 then的参数值类型为 Item[]
13REQUEST.get<Item[]>('/items')
14  .then((list) => list.forEach((i) => console.log(i.id + i.name)))

CancelToken (abort)

可通过cancel token 方式取消请求

1import { REQUEST, CancelToken } from '@txjs/taro-request'
2
3// 创建一个 tokensource
4const source = CancelToken.source();
5
6REQUEST.get('items', { skip: 100 }, { 
7  // 配置 cancelToken
8  cancelToken: source.token
9});
10
11// 需要取消操作时
12source.cancel('cancel the reqeust');

configuration

修改全局配置

1REQUEST.Defaults.retry = 2;//设置网络错误时重试次数

全部可配置内容

1{
2  /**
3  * 请求的相对地址
4  */
5  url: string
6  /**
7  * 请求方法
8  * HTTP request mthod: GET POST ...
9  */
10  method:'OPTIONS'|'GET'|'HEAD'|'POST'|'PUT'|'DELETE'|'TRACE'|'CONNECT'
11  /**
12   * 请求数据
13   * reqeust data
14   *  * **data 数据说明：**
15   *
16   * 最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String 。转换规则如下：
17   *
18   * *   对于 `GET` 方法的数据，会将数据转换成 query string（encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...）
19   * *   对于 `POST` 方法且 `header['content-type']` 为 `application/json` 的数据，会对数据进行 JSON 序列化
20   * *   对于 `POST` 方法且 `header['content-type']` 为 `application/x-www-form-urlencoded` 的数据，会将数据转换成 query string （encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...）
21   */
22  data?: any
23  /**
24   * 取消操作的 CancelToken 
25   */
26  cancelToken?: CancelToken
27  /**
28   * 接收到响应头回调
29   */
30  onHeadersReceived?: TwxTask['onHeadersReceived']
31  /**
32  * 请求的根目录
33  * Base URL for request
34  */
35  baseURL?: string
36  /**
37  * 自定义头 
38  * user defined headers
39  */
40  headers?: KeyBasicValuePair
41  /**
42   * URL Path
43   * the path parameters to be replace in path
44   * Must be a plain object
45   * @example 
46   *  url = "/{ID}/status"
47   *  param = {ID: 12345}
48   * request url will be /1234/status
49   */
50  params?: KeyBasicValuePair
51  /**
52  * 重试次数 默认重试1次
53  * retry times when fail
54  */
55  retry?: number
56  /**
57   * response data type
58   */
59  responseType?: "json" | "text" | "arraybuffer"
60  /**
61   * 修改数据或者头;返回 wx.request参数
62   * 异步返回promise
63   * You may modify the data or headers object before it is sent.
64   */
65  transformRequest?: (options) => PromiseOrValue<Exclude<HXR.options, 'complete' | 'success' | 'fail'>>
66  /**
67   * 返回数据修改，返回值作为then的输入, throw exception 抛给catch
68   * 异步返回Promise
69   * allows changes to the response data to be made before it is passed to then/catch
70   *  @example `res=>res.data`
71   */
72  transformResponse?:  (res, options) => any | Promise<any>
73}

单次请求特殊配置

1// 每次请求全部可配置参数
2// 已设置的参数会覆盖默认参数
3// 仅对此次请求生效
4REQUEST.request({
5  url: 'items',
6  method: 'POST',
7  data: {},
8  cancelToken: null,
9  baseURL: 'https://qq.com/',
10  headers: {},
11  params: null,
12  retry: 3,
13  responseType: 'json',
14  transformRequest: Http.RequestTransformation,
15  transformResponse: Http.ResponseTransformation
16})
17
18// 快速请求配置参数
19REQUEST.post('items', {}, {
20  //除了method,url和 data 不能设置其他均可设置
21  cancelToken: null,
22  baseURL: 'https://qq.com/',
23  headers: {},
24  params: null,
25  retry: 3,
26  responseType: 'json',
27  transformRequest: Http.RequestTransformation,
28  transformResponse: Http.ResponseTransformation
29})

创建一个新的Http管理对象

1// 重新创建一个Http
2const http = new Http({
3  //除了method,url，data 和cancelToken不能设置其他均可设置
4  baseURL: 'https://qq.com/',
5  headers: {},
6  params: null,
7  retry: 3,
8  responseType: 'json',
9  transformRequest: Http.RequestTransformation,
10  transformResponse: Http.ResponseTransformation
11})

LifeCircle

references

• API inspired by https://github.com/axios/axios