请求链接

描述

在加载页面阶段以及之后的交互过程中，所有需要后端接口数据的情况，都需要执行请求来完成。

请求主要是用来加载页面中的各种数据，以及发送数据到后端。

我们可能需要获取列表数据、字典数据、用户数据、表单数据、统计数据等等等等

请求链接与数据视图、执行寄连是页面中有且仅有的三大组成部分之一

通过配置请求链接，能够发起任何请求，也能处理任何返回的数据结构，更能自动绑定到页面中的字段，以供使用

既可以自己执行回调函数，也可以配合执行寄连，甚至能够关联mock来模拟任意的数据

请求列表.png

展示了接口地址、用途描述、请求参数、绑定数据四个字段内容，其中操作是一个功能列表。

类似第二行的高亮显示，表示该请求链接绑定了mock数据，只要绑定了mock数据，那么执行该请求的时候就会直接根据mock的配置返回内容，关于 mock 的更多配置详见 mock配置

显示未同步按钮，表示该条数据处于新建或者被修改过的状态，还未进行版本暂存，没有同步接口信息到代码仓库。

点击未同步即可将此条请求链接进行版本管理，点击不同步将跳过本次信息同步，可以在下次再次修改之后再同步。

页面右上角的两个按钮分别为：【通过 formId 搜索】、【新建】。

以页面的 formId 进行搜索的话会搜索到该页面所使用的全部请求链接。

操作

请求操作.png

查看

请求信息.png

可以查看请求链接的详细信息。

编辑

可以编辑请求链接的信息。

复制

可以对该请求进行复制，以达到快速新建并复用的目的。默认回显为当前请求链接的所有信息，点击完成之后会新生成一条请求链接的记录。

删除

删除该请求，并有删除前的信息确认。

页面

可以查看所有使用该请求的页面。

mock

如果一个接口目前无法返回数据，或者想要自己动态加载一些数据，或者想要根据某种结构模拟数据，那么可以通过系统配置中的数据模拟配置功能，新建相应的mock数据，然后就可以通过该功能配置相应的mock。

比如我们的歌单列表是通过数据模拟配置出来的，然后就可以点击mock：

请求配置mock.png

通过下拉框检索出需要mock数据，然后选择它，就能够给该接口配置出模拟数据，并在下方会自动展示数据结构。

所有的配置都满足mock语法，并且实时展示动态生成的数据，也可以刷新查看

这样每次返回的数据都满足所配置的数据结构，便于调试。

想要知道如何配置mock数据可参见 mock配置

查询

请求查询.png

在列表页使用【空格】键，唤起模糊搜索

可以通过接口地址、接口编码、用途描述以及ID进行查询，支持模糊查询。

点击空格即可唤出查询窗口，输入条件后按回车键执行查询。

可以多个条件同时输入，支持清空条件。

新建

点击右上角新增图标，即可打开新增弹窗。

新建请求.png

链接数据中最主要的有：接口地址、服务地址、请求方式，这三项是必填项。

接口地址：要请求的接口名，URL的后半部分，可以理解为接口路径，每个接口都存在于对应的服务下面
服务地址：要请求的服务地址，URL的前半部分，一个服务地址有多个接口，可以写成绝对的域名或ip的形式，也可以直接简写对应的服务名称，服务的名称可以通过基本信息配置页面来配置
请求方式：可选择是GET或者POST等

请求编码

主要用来标识一个请求，当需要手动调用请求链接的时候，可以通过传递该编码来发起请求。

如果请求策略设置为自动发起请求，那么可以不用设置编码，但是如果想要在之后某个时机再一次或者多次调用该接口，那么需要设置请求编码来手动调用它

一般配合 trigger 或者 prepare 使用。

trigger 主要表示会根据设定的参数及其他配置直接发起请求

prepare 主要表示先对接口做一个预准备，比如修改传递的参数，然后可以手动使用请求对象的 run 方法来发起请求

现在假设我们有一个获取课程字典的接口，设定它的请求编码为 courseDict

然后在一个按钮的点击事件中可以以如下方式调用这个接口：

function _() {
  this.R.trigger('courseDict').then(res => {
    console.log(res)
  })
}

看下接口的返回值

courseDict返回值.png

上面的代码表示了触发请求编码为 courseDict 的请求链接，获取到课程的字典。

通过 this 拿到当前对象，然后就可以取到请求对象 R，通过 trigger 方法来触发所传入的请求编码对应的请求。

如果我们接口的参数是动态的，想要在每次请求时手动修改参数的值，那么可以使用 prepare 来做一些处理

function _() {
  this.R.prepare('getDict').then(req => {
    // 可以在这修改request对象的属性
    req.request.params.code = 'sex'
    req.run().then((res) => {
      // 处理逻辑，res为接口的返回值
      console.log(res)
    })
  })
}

先看下打印出的接口返回数据

获取性别.png

上面的代码表示先预调用请求编码为 getDict 的获取字典项的请求链接，拿到该请求实例，然后将参数 code 设置为 sex，最后发起请求获得返回值。

通过 this.R 拿到请求对象，调用 prepare 方法执行请求预处理，预处理完成之后返回req对象。
再通过 req.request 拿到当前请求，然后就可以设置它的参数。
调用 req.run 方法发起请求，之后就可以对返回值进行操作。

我们再用同样的示例，换一个请求参数

function _() {
  this.R.prepare('getDict').then(req => {
    // 可以在这修改request对象的属性
    req.request.params.code = 'job'
    req.run().then((res) => {
      // 处理逻辑，res为接口的返回值
      console.log(res)
    })
  })
}

这时就可以获取到职业的字典

获取职业.png

设置参数的时候，可以获取页面上面的任何变量，比如 collectionData 中的属性。

除此之外，也可以通过 requestData.handle 对象获取对应编码的接口的信息。

根据code获取请求.png

请求参数

需要向接口提交的参数，以JS对象形式编辑并可使用变量，可从this中取值。

不区分get、post请求等方式，全部统一使用对象编写，可以对代码部分进行友好的可视化编辑。

如果没有请求体，那么请求参数会自动作为查询参数拼接在地址的后面，如果有请求体，那么请求参数将作为请求体发送出去，对于查询参数可以直接写在接口地址上面

{
  //可获取系统用户信息及 collectionData 中的变量值
  userId: this.user.id,
  code: 'foo', 
  //支持表达式
  type: this.collectionData.is_vip == 'yes' ? 1 : 0
}

实际发出去的请求参数将会变成实际的值

请求参数.png

甚至可以配置 header

{
  objectId: '',
  realName: '',
  Headers: {
  'Content-Type': 'application/x-www-form-urlencoded',
  'custom-header': 'a.b.c'
  }
}

这样就添加到了请求头上

自定义请求头.png

正常情况下，接口的返回值符合下面的形式：

{
  code: 20000,//表示成功
  data: [],//可以是任意值
  message: ''//如果有问题的提示消息
}

因为我们有统一的请求拦截和响应拦截，对于不同的code码会有不同的含义以及不同的处理方式

因此对于请求一些不符合该返回值形式的接口，将会造成误判，针对这种情况我们可以做相应的处理

如果调用外部服务接口，或者有不符合上面约定的格式，可以通过 NonStandard 字段来标识：

{
  //在请求参数中添加这对属性
  //可以是任意truthy的值
  NonStandard: true
}

这样，接口返回之后就会具有统一的数据格式：

{
  // 在这里包裹一层以统一格式，具体处理规则由调用者处理
  code: 20000,
  // 接口的实际返回值responseData作为data的值
  data: responseData
}

如果需要一段稍微复杂的逻辑处理，可以通过一个自执行函数来返回一个对象，这个对象就作为请求参数对象。

比如这样：

(() => {
  // 如果开始时间大于结束时间，那么调换这两个的值，并根据时间降序排列
  if(this.collectionData.startDate > this.collectionData.endDate) {
    return {
      startDate: endDate,
      endDate: startDate,
      sort: 'desc'
    }
  }else{
    // 否则按照时间升序排列
    return {
      startDate: startDate,
      endDate: endDate,
      sort: 'asc'
    }
  }
})()

这时我们的请求参数就能够根据具体的执行时间来实时的获取参数的值

这里只推荐写一些不太复杂的逻辑，如果有更复杂的需求，那么完全可以在实际调用的时候，使用 prepare 的方式来进行处理，也更灵活，甚至可以在某些条件下取消发送请求

除了可以在请求参数下面写，我们也可以把一些参数写在接口地址中，并且能够支持模板占位符，这样不但能够参数动态化，也能够路径动态化，可以根据具体的需求来实际操作

路径中有请求参数

getUserList?deleted=0

获取用户列表，查询未注销的

请求参数中有动态参数

getUserById?userId={this.user.id}

根据用户id获取用户信息，请求参数是动态获取的

地址中有动态路径

userInfo/{this.user.id}

可以是restful风格的接口

所有的动态参数都是用双花括号 {} 包裹，里面的 this 可以访问请求对象以及其他所有信息

绑定数据

接口请求之后的返回值data，需要绑定到一个或多个变量中。以供使用，比如返回的字典数据绑定给下拉框，返回的列表数据绑定给表格等等

可以使用多种绑定方式，将接口的返回值绑定给页面中的变量，这样就能在页面变量中获取到接口返回的数据了。

所有接口返回的数据，都默认绑定到 requestData 对象上面。

比如选择性别的下拉框的选项是从 requestData.sexList 中取值，那么当获取到接口数据的时候，就可以把返回的内容绑定到 sexList 上面。在编辑器中直接写就行。

// 绑定数据为字符串形式
sexList

也可以写成数组的形式：

// 绑定数据为数组形式
['sexList']
// 这样就可以同时绑定给多个值
['sexList', 'sexData']

绑定数据.png

只要接口一返回值就会自动进行绑定，如果未设置绑定数据，那么接口返回之后将默认不做处理，可以手动在回调函数中进行自由绑定

由于我们不用手动初始化变量，系统会自动将接口数据绑定到变量上面，因此在页面初始化加载但是接口没返回的时候，系统会自动给所有绑定的变量进行初始化。

所有默认绑定的数据，初始化的值都是数组，也就是说，在接口返回之前，默认变量的值为数组，相当于 requestData.sexList = []，当接口返回数据之后，再对这个数组进行填充

如果接口返回值为对象类型，那么可以通过json的形式进行指定。

// 绑定数据为对象形式
{
  bookInfo: {
    type: 'object',
    value: ''
  }
}

上面这个可以理解为：初始化一个变量 requestData.bookInfo = {}。

当接口返回数据时，将会变成 requestData.bookInfo = res.data

绑定为对象.png

其中type可以取 string、array、object 三种类型的值。非这三种类型，将被初始化为null。

value字段不是指的默认值，而是指的从返回值的哪个属性里面取值，如果为空就表示默认从返回数据的 data 里面取值。

如果需要深层次取值的话，支持深层选择。例如需取返回结果的 data.a.b 的值，那么可以这样写：

{
  someInfo: {
    type: 'object',
    value: 'a.b'
  }
}

就相当于是 requestData.someInfo = res.data.a.b 这样。

如果需要把返回的data数据绑定到 requestData.a.b 这种形式的变量上面，那么可以这样写：

{
  'a.b': {
    type: 'object',
    value: ''
  }
}

这样就变成了 requestData.a.b = res.data。

如果需要data中的多个数据绑定到多个变量中，常见的就是返回值是一个对象，这个对象里面有很多对属性。

如 data.a、data.b、data.c 都是数据，对应绑定到 requestData.a、requestData.b、requestData.c 上面，那么可以简写一下：

{
  'a': 'a',
  'b': 'b',
  'c': 'c',
}

这时的数据绑定就成了 requestData.a = res.data.a、requestData.b = res.data.b、requestData.c = res.data.c

也就是说属性key表示赋值给 requestData 的路径，属性值表示从 data 中取值的路径

同理我们也可以写成这样：

{
  someInfo: 'a.b'
}

属性值是字符串就直接按照路径取值，属性值是对象，那么就先根据type设定类型，然后再根据value的路径进行取值

触发策略

请求链接的调用时机，以及一些其他触发选项，是否在页面初始化阶段调用或者只在页面中通过事件手动调用等。

也是以 js 对象形式配置。

{
  immediate: true,
  sync: true,
  strategy: 'separate',
  mapping: {},
  cancel() {}
}

immediate: true 表示页面初始化时立即执行，直接发起请求，否则就只做接口的初始化，而不发送请求，在之后可以通过请求编码进行手动调用。

sync: true 表示将请求变成同步请求，只有该请求完成之后才会继续后面的逻辑。手动触发的接口该参数无效。

strategy: 'separate' 主要应用在设计页面的场景，如果一个接口没有动态参数，那么可以设置为 separate，表示不依赖其他状态，可以单独使用，从而在配置的时候就可以直接发起请求，否则需要手动设定参数。配置该属性可方便在页面设计器中直接调用请求链接，方便设计页面时可实时查看接口返回效果。

mapping：设置接口返回字段的映射，如：下拉框绑定的属性为 label、value，但是接口返回的数据对应标识为 dicName 、dicCode，那么我们就可以设置为：

{
  mapping: {
    label: 'dicName',
    value: 'dicCode'
  }
}

也就是说我们可以把不同的返回数据的字段都改成统一的格式以方便处理和使用

我们既可以写任意多个属性对，也可以给每个属性对起任意的名字

{
  mapping: {
    newField: 'currentField'
    ...
  }
}

mapping中还可以指定一个额外的关键字 resultPath，表示取值的路径

{
  mapping: {
    resultPath: 'a.b',
    newField: 'currentField'
    ...
  }
}

这样就会从返回数据进行深层查找，相当于给 res.data.a.b 数据应用mapping设定的转换规则

拿刚才获取性别的接口来举例，未设置 mapping 时，接口本来的返回值应该是这样的：

接口返回值.png

现在我们把 code 转化成 value，name 转化成 label

{
  mapping: {
    label: 'name',
    value: 'code'
  }
}

那么返回之后的数据在 requestData.sexList 中将会是这样：

mapping转换.png

cancel：有一种情况就是，虽然页面配置了自动触发的请求，但是目前该页面不需要发送该请求。

换句话说如果不满足某些条件就不请求接口，那么我们可以用它来取消接口的发送，值为一个函数，当返回 truthy 的值时，那么该请求将被过滤掉，否则正常发送请求。例如：

{
  cancel: () => {
    return !this.user.id
  }
}

假如上面表示一个获取历史浏览记录的接口，那么当用户还未登录时，将不触发请求。

回调函数 请求完成之后的回调函数，直接写方法体即可，主要用来做接口调用完毕后的处理，当一个接口返回数据时，会执行回调函数，可以进行一个额外的处理。

会先于其他处理，回调函数处理完成后，才会完成数据的绑定操作等等，可以理解成是对返回数据的拦截。

可以访问 data 和 result 字段，data 表示返回数据的 data 值，result 表示接口返回的原始数据，也就是 result.data === data 恒成立，可以在这里面使用 runIt 来执行寄连。

// 接口返回值，包含code、data、message等
console.log(result);
// 接口返回的数据，对应data
console.log(data);
// 调用编码为setInitData的执行寄连，并传递参数
this.P.runIt('setInitData', data);
// 也可以访问collectionData
console.log(this.collectionData)

接口回调函数代码无需要包在 function 中。可以通过 this 访问页面中的任意变量。

请求链接 ​

描述 ​

操作 ​

查询 ​

新建 ​

请求编码 ​

请求参数 ​

绑定数据 ​

触发策略 ​

请求链接

描述

操作

查询

新建

请求编码

请求参数

绑定数据

触发策略