[译] superagent中文使用文档
superagent是nodejs里一个非常方便的客户端请求代理模块,当你想处理get,post,put,delete,head请求时,你就应该想起该用它了:)
SuperAgentsuperagent 是一个轻量的,渐进式的ajax api,可读性好,学习曲线低,内部依赖nodejs原生的请求api,适用于nodejs环境下.
一个简单的post请求,并设置请求头信息的例子
request .post(/api/pet) .send({ name: Manny, species: cat }) .set(X-API-Key, foobar) .set(Accept, application/json) .end(function(res){ if (res.ok) { alert(yay got + JSON.stringify(res.body)); } else { alert(Oh no! error + res.text);
这个链接文档,是用Mochas文档自动输出的,下面提供了这个测试文档对应的源文件
一个请求的初始化可以用请求对象里合适的方法来执行,然后调用end()来发送请求,下面是一个简单的get请求
request .get(/search) .end(function(res){
请求方法也可以通过参数传递:
request(GET, /search).end(callback);
node客户端也允许提供绝对路径:
request .get(http://example.com/search) .end(function(res){
delete,head,post,put和别的http动作都可以使用,来换个方法看看:
request .head(/favicon.ico) .end(function(res){
delete是一个特列,因为它是系统保留的关键字,所以应该用.del()这个名字:
request .del(/user/1) .end(function(res){
http请求默认的方法为get,所以就像你看到的,下面的这个例子也是可用的:
request(/search, function(res){设置头字段
设置头字段非常简单,只需调用.set()方法,传递一个名称和值就行:
request .get(/search) .set(API-Key, foobar) .set(Accept, application/json) .end(callback);
你也可以直接传递一个对象进去,这样一次就可以修改多个头字段:
request .get(/search) .set({ API-Key: foobar, Accept: application/json }) .end(callback);Get请求
当使用get请求传递查询字符串的时候,用.query()方法,传递一个对象就可以,下面的代码将产生一个/search?query=Manny range=1..5 order=desc请求:
request .get(/search) .query({ query: Manny }) .query({ range: 1..5 }) .query({ order: desc }) .end(function(res){
或者传一个单独的大对象:
request .get(/search) .query({ query: Manny, range: 1..5, order: desc }) .end(function(res){
.query()方法也允许传递字符串:
request .get(/querystring) .query(search=Manny range=1..5) .end(function(res){
或者字符串拼接:
request .get(/querystring) .query(search=Manny) .query(range=1..5) .end(function(res){POST/PUT请求
一个典型的json post请求看起来就像下面的那样,设置一个合适的Content-type头字段,然后写入一些数据,在这个例子里只是json字符串:
request.post(/user) .set(Content-Type, application/json) .send({"name":"tj","pet":"tobi"}) .end(callback)
因为json非常通用,所以就作为默认的Content-type,下面的例子跟上面的一样:
request.post(/user) .send({ name: tj, pet: tobi }) .end(callback)
或者调用多次.send()方法:
request.post(/user) .send({ name: tj }) .send({ pet: tobi }) .end(callback)
默认发送字符串,将设置Content-type为application/x-www-form-urlencoded,多次调用将会通过 来连接,这里的结果为name=tj pet=tobi:
request.post(/user) .send(name=tj) .send(pet=tobi) .end(callback);
superagent的请求数据格式化是可以扩展的,不过默认支持form和json两种格式,想发送数据以application/x-www-form-urlencoded类型的话,则可以简单的调用.type()方法传递form参数就行,这里默认是json,下面的请求将会postname=tj pet=tobi内容:
request.post(/user) .type(form) .send({ name: tj }) .send({ pet: tobi }) .end(callback)
注意:form是form-data和urlencoded的别名,为了向后兼容
设置Content-Type常见的方案是使用.set()方法:
request.post(/user) .set(Content-Type, application/json)
一个简便的方法是调用.type()方法,传递一个规范的MIME名称,包括type/subtype,或者一个简单的后缀就像xml,json,png这样,例如:
request.post(/user) .type(application/json) request.post(/user) .type(json) request.post(/user) .type(png)设置接受类型
跟.type()简便方法一样,这里也可以调用.accept()方法来设置接受类型,这个值将会被request.types所引用,支持传递一个规范的MIME名称,包括type/subtype,或者一个简单的后缀就像xml,json,png这样,例如:
request.get(/user) .accept(application/json) request.get(/user) .accept(json) request.get(/user) .accept(png)查询字符串
当用.send(obj)方法来发送一个post请求,并且希望传递一些查询字符串,可以调用.query()方法,比如向?format=json dest=/login发送post请求:
request .post(/) .query({ format: json }) .query({ dest: /login }) .send({ post: data, here: wahoo }) .end(callback);解析响应内容
superagent会解析一些常用的格式给请求者,当前支持application/x-www-form-urlencoded,application/json,multipart/form-data.
JSON/Urlencodedres.body是解析后的内容对象,比如一个请求响应{"user":{"name":"tobi"}}字符串,res.body.user.name将会返回tobi,同样的,x-www-form-urlencoded格式的user[name]=tobi解析完的值,也是一样的.
Multipartnodejs客户端通过Formidable模块来支持multipart/form-data类型,当解析一个multipart响应时,res.files属性就可以用.假设一个请求响应下面的数据:
--whoop Content-Disposition: attachment; name="image"; filename="tobi.png" Content-Type: image/png ... data here ... --whoop Content-Disposition: form-data; name="name" Content-Type: text/plain --whoop--
你将可以获取到res.body.name名为Tobi,res.files.image为一个file对象,包括一个磁盘文件路径,文件名称,还有其它的文件属性.
响应一般会提供很多有用的标识以及属性,都在response对象里,按照respone.text,解析后的response.body,头字段,一些标识的顺序来排列.
Response textres.text包含未解析前的响应内容,一般只在mime类型能够匹配text/,json,x-www-form-urlencoding的情况下,默认为nodejs客户端提供,这是为了节省内存.因为当响应以文件或者图片大内容的情况下影响性能.
Response body跟请求数据自动序列化一样,响应数据也会自动的解析,当为一个Content-Type定义一个解析器后,就能自动解析,默认解析包含application/json和application/x-www-form-urlencoded,可以通过访问res.body来访问解析对象.
Response header fieldsres.header包含解析之后的响应头数据,键值都是node处理成小写字母形式,比如res.header[content-length].
Response Content-TypeContent-Type响应头字段是一个特列,服务器提供res.type来访问它,默认res.charset是空的,如果有的话,则自动填充,例如Content-Type值为text/html; charset=utf8,则res.type为text/html,res.charst为utf8.
Response status响应状态标识可以用来判断请求是否成功,除此之外,可以用superagent来构建理想的restful服务器,这些标识目前定义为:
var type = status / 100 | 0; // status / class res.status = status; res.statusType = type; // basics res.info = 1 == type; res.ok = 2 == type; res.clientError = 4 == type; res.serverError = 5 == type; res.error = 4 == type || 5 == type; // sugar res.accepted = 202 == status; res.noContent = 204 == status || 1223 == status; res.badRequest = 400 == status; res.unauthorized = 401 == status; res.notAcceptable = 406 == status; res.notFound = 404 == status; res.forbidden = 403 == status;
可以通过req.abort()来中止请求.
可以通过req.timeout()来定义超时时间,然后当超时错误发生时,为了区别于别的错误,err.timeout属性被定义为超时时间,注意,当超时错误发生后,后续的请求都会被重定向.不是每个请求.
nodejs客户端可以通过两种方式来达到验证的目的,第一个是传递一个像这样的url,user:pass:
request.get(http://tobi:learnboost@local).end(callback);
第二种是调用.auth()方法:
request .get(http://local) .auth(tobo, learnboost) .end(callback);跟随重定向
默认是向上跟随5个重定向,不过可以通过调用.res.redirects(n)来设置个数:
request .get(/some.png) .redirects(2) .end(callback);
nodejs客户端允许使用一个请求流来输送数据,比如请求一个文件作为输出流:
var request = require(superagent) , fs = require(fs); var stream = fs.createReadStream(path/to/my.json); var req = request.post(/somewhere); req.type(json); stream.pipe(req);
或者输送一个响应流到文件中:
var request = require(superagent) , fs = require(fs); var stream = fs.createWriteStream(path/to/my.json); var req = request.get(/some.json); req.pipe(stream);
superagent用来构建复合请求非常不错,提供了低级和高级的api方法.
低级的api是使用多个部分来表现一个文件或者字段,.part()方法返回一个新的部分,提供了跟request本身相似的api方法.
var req = request.post(/upload); req.part() .set(Content-Type, image/png) .set(Content-Disposition, attachment; filename="myimage.png") .write(some image data) .write(some more image data); req.part() .set(Content-Disposition, form-data; name="name") .set(Content-Type, text/plain) .write(tobi); req.end(callback);
上面提及的高级api方法,可以通用.attach(name, [path], [filename])和.field(name, value)这两种形式来调用.添加多个附件也比较简单,只需要给附件提供自定义的文件名称,同样的基础名称也要提供.
request .post(/upload) .attach(avatar, path/to/tobi.png, user.png) .attach(image, path/to/loki.png) .attach(file, path/to/jane.png) .end(callback);
跟html的字段很像,你可以调用.field(name,value)方法来设置字段,假设你想上传一个图片的时候带上自己的名称和邮箱,那么你可以像下面写的那样:
request .post(/upload) .field(user[name], Tobi) .field(user[email], tobi@learnboost.com) .attach(image, path/to/tobi.png) .end(callback);
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的情况下才行.
request .get(http://localhost:4001/) .withCredentials() .end(function(res){ assert(200 == res.status); assert(tobi == res.text); next();
当发送错误时,superagent首先会检查回调函数的参数数量,当err参数提供的话,参数就是两个,如下:
request .post(/upload) .attach(image, path/to/tobi.png) .end(function(err, res){
当省略了回调函数,或者回调只有一个参数的话,可以添加error事件的处理.
request .post(/upload) .attach(image, path/to/tobi.png) .on(error, handle) .end(function(res){
注意:superagent默认情况下,对响应4xx和5xx的认为不是错误,例如当响应返回一个500或者403的时候,这些状态信息可以通过res.error,res.status和其它的响应属性来查看,但是没有任务的错误对象会传递到回调函数里或者emit一个error事件.正常的error事件只会发生在网络错误,解析错误等.
当产生一个4xx或者5xx的http错误响应,res.error提供了一个错误信息的对象,你可以通过检查这个来做某些事情.
if (res.error) { alert(oh no + res.error.message); } else { alert(got + res.status + response);
superagent是一个非常实用的http代理模块,推荐大家使用.
itextpdf 中文不显示问题 # 现象 itextpdf 打印时中文字体显示不出来,莫名其妙的消失不见了。具体现象如下图所示。 ![](https://ata2-img.oss-cn-zhangjiakou.aliyuncs.com/neweditor/ddc69588-4fc6-46ff-9d33-07f99340c963.png) 真正的理想情况如下图。 ![](https://ata2-img.oss-cn-zhangj
相关文章
- [Hadoop]Hive r0.9.0中文文档(一)之数据操作语句
- CefSharp中文帮助文档
- php Date()函数输出中文年月日时分秒
- Date日期类型转化成中文字符串
- Nmap中文手册
- IdentityServer4中文文档
- android 中文文档
- 如何在linux系统安装中文输入法
- Android官方中文文档
- Android2.2 API 中文文档系列(6) —— ImageView
- zabbix安装中文语言包及中文乱码的解决(zabbix5.0)
- MySQL中文全文索引插件 mysqlcft 1.0.0 安装使用文档[原创]
- 使用Discuz关键词服务器实现PHP中文分词
- 如何找到msdn中文文档呢?
- 千呼万唤始出来,微软Power BI简体中文版官网终于上线了,中文文档也全了。。
- 满江红开放技术研究组织发布Seam 2.0中文文档RC版
- python3读中文文档报错:UnicodeDecodeError: ‘gbk‘ codec can‘t decode byte 0xa6 in ...
- Socks5协议中文文档
- Ubuntu18.04谷歌输入法中文候选此框消失问题(三十八)
- char类型能否存储一个中文字符?为什么