Skip to content

网络 $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 结构:

  • 当发送 GETHEADDELETE 请求时,默认会将 body 作为 query string 拼接到 url 后方(后续会去掉这个逻辑)
  • 当设置了 files,header 中的 Content-Type 将被强制设置为 multipart/form-data,body 将作为 form-data 中其他的参数
  • 当 header 中的 Content-Typeapplication/json 时,body 将会以 json 的形式编码
  • 当 header 中的 Content-Typeapplication/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.get(object)

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

发送一个 GET 请求:

js
$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.streamRequest(object) Bob 1.8.0+ 可用

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

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

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
  }
});

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

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

Promise

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

例如:

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