网络 $http

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

$http.request(object)

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

参数	类型	说明
method	string	GET/POST/DELETE 等
url	string	链接
header	object	http header
body	object / $data	http body
files	array	文件列表
timeout	number	请求超时时间，单位秒
cancelSignal	$signal	取消信号，可传入该对象用于取消请求 Bob 1.8.0+ 可用
streamHandler	function	流数据回调函数，仅流式请求可用，详情见下方 $http.streamRequest 方法 Bob 1.8.0+ 可用
handler	function	回调函数

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	二进制数据
name	string	上传表单中的名称
filename	string	上传之后的文件名
content-type	string	文件格式

handler

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

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

关于 data 参数：

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

response 包含请求响应信息:

属性	类型	说明
url	string	url
MIMEType	string	MIME 类型
expectedContentLength	number	长度
textEncodingName	string	编码
suggestedFilename	string	建议的文件名
statusCode	number	HTTP 状态码
headers	object	HTTP header

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

Bob 1.8.0 之前的结构

属性	类型	说明
domain	string	domain
code	number	code
userInfo	object	userInfo
localizedDescription	string	描述
localizedFailureReason	string	原因
localizedRecoverySuggestion	string	建议

Bob 1.8.0 及以后的结构

属性	类型	说明
message	string	描述
debugMessage	string	详细描述，用于 debug

示范

尝试发送一个网络请求：

$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 请求：

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

$http.post(object)

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

发送一个 GET 请求：

$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 回调函数的参数如下:

属性	类型	说明
text	string	流式数据解析为 utf8 字符串，可能为空
rawData	$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 对象。

例如：

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