superagent是nodejs里一个非常方便的客户端请求代理模块,当你想处理get,post,put,delete,head请求时,你就应该想起该用它了:) SuperAgent superagent 是一个轻量的,渐进式的ajax api,可读性好,学习曲线低,内部依赖nodejs…
SupreAgent
一个简单的post请求示例
1 | request |
请求基础
一个请求的初始化可以用请求对象里合适的方法来执行,然后调用end()
来发送请求,下面是一个简单的get
请求
1 | request |
请求方法也可以通过参数传递
1 | request('GET','/search').end(callback); |
node
客户端也允许提供绝对路径
1 | request |
delete
,head
,post
,put
和别的http动作都可以使用,例如
1 | request |
delete
是一个特列,因为它是系统保留关键字,所以应该使用.del
这个名字
1 | request |
http请求默认方法为get
,如下
1 | request('/search',function(res){ |
设置头字段
设置头字段,只需调用.set()
方法,传递一个名称和值就行
1 | request |
你也可以直接传递一个对象进去,这样一次就可以修改多个头字段:
1 | request |
Get请求
当使用get
请求传递查询字符串的时候,用.query()
方法,传递一个对象就可以,下面的代码将产生一个/search?query=Manny&range=1..5&order=desc
请求:
1 | request |
或者传一个单独的大对象:
1 | request |
.query()
方法也允许传递字符串:
1 | request |
或者字符串拼接:
1 | request |
POST/PUT请求
一个典型的json post请求看起来就像下面的那样,设置一个合适的Content-type头字段,然后写入一些数据,在这个例子里只是json字符串:
1 | request.post('/user') |
因为json非常通用,所以就作为默认的Content-type
,下面的例子跟上面的一样:
1 | request.post('/user') |
或者调用多次.send()
方法:
1 | request.post('/user') |
默认发送字符串,将设置Content-type
为application/x-www-form-urlencoded
,多次调用将会通过&
来连接,这里的结果为name=tj&pet=tobi:
1 | request.post('/user') |
superagent
的请求数据格式化是可以扩展的,不过默认支持form
和json
两种格式,想发送数据以application/x-www-form-urlencoded
类型的话,则可以简单的调用.type()
方法传递form
参数就行,这里默认是json
,下面的请求将会postname=tj&pet=tobi
内容:
1 | request.post('/user') |
注意:form
是form-data
和urlencoded
的别名,为了向后兼容
设置Content-Type
常见的方案是使用.set()
方法:
1 | request.post('/user') |
一个简便的方法是调用.type()
方法,传递一个规范的MIME
名称,包括type/subtype
,或者一个简单的后缀就像xml
,json
,png
这样,例如:
1 | request.post('/user') |
设置接受类型
跟.type()
简便方法一样,这里也可以调用.accept()
方法来设置接受类型,这个值将会被request.types
所引用,支持传递一个规范的MIME
名称,包括type/subtype
,或者一个简单的后缀就像xml
,json
,png
这样,例如:
1 | request.get('/user') |
1 | request.get('/user') |
1 | request.get('/user') |
查询字符串
当用.send(obj)
方法来发送一个post
请求,并且希望传递一些查询字符串,可以调用.query()
方法,比如向?format=json&dest=/login
发送post
请求:
1 | request |
解析响应内容
superagent
会解析一些常用的格式给请求者,当前支持application/x-www-form-urlencoded,application/json,multipart/form-data
.
JSON/Urlencoded
res.body
是解析后的内容对象,比如一个请求响应'{"user":{"name":"tobi"}}'
字符串,res.body.user.name
将会返回tobi
,同样的,x-www-form-urlencoded
格式的user[name]=tobi
解析完的值,也是一样的.
Multipart
nodejs
客户端通过Formidable
模块来支持multipart/form-data
类型,当解析一个multipart
响应时,res
.files
属性就可以用.假设一个请求响应下面的数据:
1 | --whoop |
你将可以获取到res.body.name
名为'Tobi'
,res.files.image
为一个file
对象,包括一个磁盘文件路径,文件名称,还有其它的文件属性.
响应属性
响应一般会提供很多有用的标识以及属性,都在response
对象里,按照respone.text
,解析后的response.body
,头字段,一些标识的顺序来排列.
Response text
res.text
包含未解析前的响应内容,一般只在mime类型能够匹配text/
,json
,x-www-form-urlencoding
的情况下,默认为nodejs
客户端提供,这是为了节省内存.因为当响应以文件或者图片大内容的情况下影响性能.
Response body
跟请求数据自动序列化一样,响应数据也会自动的解析,当为一个Content-Type
定义一个解析器后,就能自动解析,默认解析包含application/json
和application/x-www-form-urlencoded
,可以通过访问res.body
来访问解析对象.
Response header fields
res.header
包含解析之后的响应头数据,键值都是node
处理成小写字母形式,比如res.header['content-length']
.
Response Content-Type
Content-Type
响应头字段是一个特列,服务器提供res.type
来访问它,默认res.charset
是空的,如果有的话,则自动填充,例如Content-Type
值为text/html
; charset=utf8
,则res.type
为text/html
,res.charst
为utf8
.
Response status
响应状态标识可以用来判断请求是否成功,除此之外,可以用superagent
来构建理想的restful
服务器,这些标识目前定义为:
1 | var type = status / 100 | 0; |
中止请求
可以通过req.abort()
来中止请求.
请求超时
可以通过req.timeout()
来定义超时时间,然后当超时错误发生时,为了区别于别的错误,err.timeout
属性被定义为超时时间,注意,当超时错误发生后,后续的请求都会被重定向.不是每个请求.
基础验证
nodejs
客户端可以通过两种方式来达到验证的目的,第一个是传递一个像这样的url
,user:pass:
1 | request.get('http://tobi:learnboost@local').end(callback); |
第二种是调用.auth()
方法:
1 | request |
跟随重定向
默认是向上跟随5个重定向,不过可以通过调用.res.redirects(n)
来设置个数:
1 | request |
管道数据
nodejs
客户端允许使用一个请求流来输送数据,比如请求一个文件作为输出流:
1 | var request = require('superagent') |
或者输送一个响应流到文件中:
1 | var request = require('superagent') |
复合请求
superagent
用来构建复合请求非常不错,提供了低级和高级的api
方法.
低级的api
是使用多个部分来表现一个文件或者字段,.part()
方法返回一个新的部分,提供了跟request
本身相似的api
方法.
1 | var req = request.post('/upload'); |
附加文件
上面提及的高级api
方法,可以通用.attach(name, [path], [filename])
和.field(name, value)
这两种形式来调用.添加多个附件也比较简单,只需要给附件提供自定义的文件名称,同样的基础名称也要提供.
1 | request |
字段值
跟html
的字段很像,你可以调用.field(name,value)
方法来设置字段,假设你想上传一个图片的时候带上自己的名称和邮箱,那么你可以像下面写的那样:
1 | request |
压缩
nodejs
客户端本身就提供了压缩响应内容,所以你不需要做任何其它事情.
缓冲响应
为了强迫缓冲res.text
这样的响应内容,可以调用req.buffer()
方法,想取消默认的文本缓冲响应像text/plain
,text/html
这样的,可以调用req.buffer(false)
方法
当缓冲res.buffered
标识提供了,那么就可以在一个回调函数里处理缓冲和没缓冲的响应.
跨域资源共享
.withCredentials()
方法可以激活发送原始cookie
的能力,不过只有在Access-Control-Allow-Origin
不是一个通配符(*)
,并且Access-Control-Allow-Credentials
为'true'
的情况下才行.
1 | request |
异常处理
当发送错误时,superagent
首先会检查回调函数的参数数量,当err
参数提供的话,参数就是两个,如下:
1 | request |
当省略了回调函数,或者回调只有一个参数的话,可以添加error
事件的处理.
1 | request |
注意:superagent
默认情况下,对响应4xx
和5xx
的认为不是错误,例如当响应返回一个500
或者403
的时候,这些状态信息可以通过res.error
,res.status
和其它的响应属性来查看,但是没有任务的错误对象会传递到回调函数里或者emit一个error
事件.正常的error
事件只会发生在网络错误,解析错误等.
当产生一个4xx
或者5xx
的http
错误响应,res.error
提供了一个错误信息的对象,你可以通过检查这个来做某些事情.
1 | if (res.error) { |