Bob

外观

网络 $http ​

发送网络请求可能是插件最核心的需求了，$http 就是用来解决这个问题的。

$http.request(object) ​

发送一个 HTTP 请求，参数是一个 object 类型，可具有以下属性：

参数类型说明
methodstringGET/POST/DELETE 等
urlstring链接
headerobjecthttp header
bodyobject / $datahttp body
filesarray文件列表
timeoutnumber请求超时时间，单位秒
cancelSignal$signal取消信号，可传入该对象用于取消请求 Bob 1.8.0+ 可用
streamHandlerfunction流数据回调函数，仅流式请求可用，详情见下方 $http.streamRequest 方法 Bob 1.8.0+ 可用
handlerfunction回调函数

body ​

其中 body 可以是一个 JSON 结构或 $data 类型的数据。

如果 body 为一个 JSON 结构：

  • 当发送 GET、HEAD 和 DELETE 请求时，默认会将 body 作为 query string 拼接到 url 后方（后续会去掉这个逻辑）
  • 当设置了 files，header 中的 Content-Type 将被强制设置为 multipart/form-data，body 将作为 form-data 中其他的参数
  • 当 header 中的 Content-Type 为 application/json 时，body 将会以 json 的形式编码
  • 当 header 中的 Content-Type 为 application/x-www-form-urlencoded 时，body 将会转换成 a=b&c=d 的 query 结构
  • Content-Type 默认值是 application/x-www-form-urlencoded

如果 body 是 $data 类型的数据：

这时 http body 不会进行编码，会直接使用传进来的数据。

files ​

某些接口上传文件需要以 multipart/form-data 的形式，此时需要设置 files 参数，files 是一个数组，包含的元素需要以如下结构：

参数类型说明
data$data二进制数据
namestring上传表单中的名称
filenamestring上传之后的文件名
content-typestring文件格式

handler ​

handler 是网络请求的回调，该回调函数只有一个参数，结构如下：

参数类型说明
dataobject / string / $data解析过后的数据
rawData$data返回的原始的二进制数据
responseresponse请求响应信息
errorerror错误

关于 data 参数：

  • 返回数据为 json 数据时会自动解析为 object
  • 解析 json 失败时，会尝试解析为 UTF-8 格式的 string
  • 如果再次失败，会直接设置为 $data 类型的原始二进制数据

response 包含请求响应信息:

属性类型说明
urlstringurl
MIMETypestringMIME 类型
expectedContentLengthnumber长度
textEncodingNamestring编码
suggestedFilenamestring建议的文件名
statusCodenumberHTTP 状态码
headersobjectHTTP header

当存在 error 参数，代表网络请求错误，结构如下：

Bob 1.8.0 之前的结构

属性类型说明
domainstringdomain
codenumbercode
userInfoobjectuserInfo
localizedDescriptionstring描述
localizedFailureReasonstring原因
localizedRecoverySuggestionstring建议

Bob 1.8.0 及以后的结构

属性类型说明
messagestring描述
debugMessagestring详细描述，用于 debug

示范 ​

尝试发送一个网络请求：

js
$http.request({
  method: "POST",
  url: "https://apple.com",
  header: {
    k1: "v1",
    k2: "v2"
  },
  body: {
    k1: "v1",
    k2: "v2"
  },
  handler: function(resp) {
    var data = resp.data
  }
});
$http.request({
  method: "POST",
  url: "https://apple.com",
  header: {
    k1: "v1",
    k2: "v2"
  },
  body: {
    k1: "v1",
    k2: "v2"
  },
  handler: function(resp) {
    var data = resp.data
  }
});

$http.get(object) ​

所有参数和 request 方法一致，唯一就是自动将 method 方法设置为 GET。

发送一个 GET 请求：

js
$http.get({
  url: "https://apple.com",
  handler: function(resp) {
    var data = resp.data
  }
});
$http.get({
  url: "https://apple.com",
  handler: function(resp) {
    var data = resp.data
  }
});

$http.post(object) ​

所有参数和 request 方法一致，唯一就是自动将 method 方法设置为 POST。

发送一个 GET 请求：

js
$http.post({
  url: "https://apple.com",
  handler: function(resp) {
    var data = resp.data
  }
});
$http.post({
  url: "https://apple.com",
  handler: function(resp) {
    var data = resp.data
  }
});

$http.streamRequest(object) Bob 1.8.0+ 可用 ​

发送流式请求，流式请求与 $http.request 用法基本一致，主要有以下区别：

  • 请求参数不支持 files 属性
  • 请求参数增加 streamHandler 用于接收流式数据回调，数据都在该函数下发
  • 流式请求 handler 回调的 resp 对象不包含 data 和 rawData 属性

streamHandler 回调函数的参数如下:

属性类型说明
textstring流式数据解析为 utf8 字符串，可能为空
rawData$data原始二进制数据，一定不为空

尝试发送一个流式请求：

js
$http.streamRequest({
  method: "POST",
  url: "https://apple.com",
  header: {
    k1: "v1",
    k2: "v2"
  },
  body: {
    k1: "v1",
    k2: "v2"
  },
  streamHandler: function(stream) {
    var text = stream.text
    var rawData = stream.rawData
  },
  handler: function(resp) {
    var data = resp.data
  }
});
$http.streamRequest({
  method: "POST",
  url: "https://apple.com",
  header: {
    k1: "v1",
    k2: "v2"
  },
  body: {
    k1: "v1",
    k2: "v2"
  },
  streamHandler: function(stream) {
    var text = stream.text
    var rawData = stream.rawData
  },
  handler: function(resp) {
    var data = resp.data
  }
});

这篇文章 详细描述了插件如何实现流式输出。

issue #451 对流式请求做了一些补充说明，有需要可以了解下。

Promise ​

$http 所有 API 支持 Promise，如果设置了 handler 参数，将通过该回调函数返回数据；如果没有设置 handler 参数，将返回一个 Promise 对象。

例如：

js
async function foo() {
    var resp = await $http.get({url: "https://apple.com"});
}
async function foo() {
    var resp = await $http.get({url: "https://apple.com"});
}

Copyright © 2019-present Zongyi He