superagent 中文网
小型渐进式客户端 HTTP 请求库和具有相同 API 的 Node.js 模块,支持许多高级 HTTP 客户端功能。为 转发电子邮件 和 Lad 进行维护。
¥Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features. Maintained for Forward Email and Lad.
安装
¥Install
npm:
npm install superagent
yarn:
yarn add superagent
用法
¥Usage
Node
const superagent = require('superagent');
// callback
superagent
.post('/api/pet')
.send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
.set('X-API-Key', 'foobar')
.set('accept', 'json')
.end((err, res) => {
// Calling the end function will send the request
});
// promise with then/catch
superagent.post('/api/pet').then(console.log).catch(console.error);
// promise with async/await
(async () => {
try {
const res = await superagent.post('/api/pet');
console.log(res);
} catch (err) {
console.error(err);
}
})();
浏览器
¥Browser
适用于浏览器的 superagent
的最小化版本只有 50 KB(最小化和压缩)。
¥The browser-ready, minified version of superagent
is only 50 KB (minified and gzipped).
此模块的浏览器就绪版本可通过 jsdelivr、unpkg 获得,也可在 superagent
包下载中的 node_modules/superagent/dist
文件夹中获得。
¥Browser-ready versions of this module are available via jsdelivr, unpkg, and also in the node_modules/superagent/dist
folder in downloads of the superagent
package.
请注意,我们还提供未压缩的版本,文件扩展名为
.js
,而不是.min.js
。¥Note that we also provide unminified versions with
.js
instead of.min.js
file extensions.
VanillaJS
如果你只是在任何地方使用 <script>
标签,那么这就是你的解决方案!
¥This is the solution for you if you're just using <script>
tags everywhere!
<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
<script src="https://cdn.jsdelivr.net/npm/superagent"></script>
<!-- if you wish to use unpkg.com instead: -->
<!-- <script src="https://unpkg.com/superagent"></script> -->
<script type="text/javascript">
(function() {
// superagent is exposed as `window.superagent`
// if you wish to use "request" instead please
// uncomment the following line of code:
// `window.request = superagent;`
superagent
.post('/api/pet')
.send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
.set('X-API-Key', 'foobar')
.set('accept', 'json')
.end(function (err, res) {
// Calling the end function will send the request
});
})();
</script>
Bundler
如果你使用的是 browserify、webpack、rollup 或其他打包器,那么你可以遵循与上述 Node 相同的用法。
¥If you are using browserify, webpack, rollup, or another bundler, then you can follow the same usage as Node above.
支持的平台
¥Supported Platforms
-
Node:v14.18.0+
-
浏览器(参见 .browserslistrc):
¥Browsers (see .browserslistrc):
npx browserslist
and_chr 102
and_ff 101
and_qq 10.4
and_uc 12.12
android 101
chrome 103
chrome 102
chrome 101
chrome 100
edge 103
edge 102
edge 101
firefox 101
firefox 100
firefox 91
ios_saf 15.5
ios_saf 15.4
ios_saf 15.2-15.3
ios_saf 15.0-15.1
ios_saf 14.5-14.8
ios_saf 14.0-14.4
ios_saf 12.2-12.5
kaios 2.5
op_mini all
op_mob 64
opera 86
opera 85
safari 15.5
safari 15.4
samsung 17.0
samsung 16.0
所需的浏览器功能
¥Required Browser Features
我们建议使用 https://cdnjs.cloudflare.com/polyfill(特别是上面 VanillaJS 中提到的打包包):
¥We recommend using https://cdnjs.cloudflare.com/polyfill (specifically with the bundle mentioned in VanillaJS above):
<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
-
Opera 85、iOS Safari 12.2-12.5 不支持 WeakRef
¥WeakRef is not supported in Opera 85, iOS Safari 12.2-12.5
-
iOS Safari 12.2-12.5 不支持 BigInt
¥BigInt is not supported in iOS Safari 12.2-12.5
插件
¥Plugins
SuperAgent 可通过插件轻松扩展。
¥SuperAgent is easily extended via plugins.
const nocache = require('superagent-no-cache');
const superagent = require('superagent');
const prefix = require('superagent-prefix')('/static');
superagent
.get('/some-url')
.query({ action: 'edit', city: 'London' }) // query string
.use(prefix) // Prefixes *only* this request
.use(nocache) // Prevents caching of *only* this request
.end((err, res) => {
// Do something
});
现有插件:
¥Existing plugins:
-
superagent-no-cache - 通过包含 Cache-Control 标头来防止缓存
¥superagent-no-cache - prevents caching by including Cache-Control header
-
superagent-prefix - 为绝对 URL 加前缀(在测试环境中很有用)
¥superagent-prefix - prefixes absolute URLs (useful in test environment)
-
superagent-suffix - 使用给定路径为 URL 加后缀
¥superagent-suffix - suffix URLs with a given path
-
superagent-mock - 通过根据请求的 URL 返回数据装置来模拟 HTTP 调用
¥superagent-mock - simulate HTTP calls by returning data fixtures based on the requested URL
-
superagent-mocker — 模拟 REST API
¥superagent-mocker — simulate REST API
-
superagent-cache - 具有内置、灵活缓存的全局 SuperAgent 补丁
¥superagent-cache - A global SuperAgent patch with built-in, flexible caching
-
superagent-cache-plugin - 具有内置、灵活缓存的 SuperAgent 插件
¥superagent-cache-plugin - A SuperAgent plugin with built-in, flexible caching
-
superagent-jsonapify - 用于 superagent 的轻量级 json-api 客户端插件
¥superagent-jsonapify - A lightweight json-api client addon for superagent
-
superagent-serializer - 将服务器负载转换为不同的情况
¥superagent-serializer - Converts server payload into different cases
-
superagent-httpbackend - 使用 AngularJS 的 $httpBackend 语法存根请求
¥superagent-httpbackend - stub out requests using AngularJS' $httpBackend syntax
-
superagent-throttle - 排队并智能地限制请求
¥superagent-throttle - queues and intelligently throttles requests
-
superagent-charset - 为 node 的 SuperAgent 添加字符集支持
¥superagent-charset - add charset support for node's SuperAgent
-
superagent-verbose-errors - 在失败请求的错误消息中包含响应正文
¥superagent-verbose-errors - include response body in error messages for failed requests
-
superagent-declare - 用于 SuperAgent 的简单 declarative API
¥superagent-declare - A simple declarative API for SuperAgent
-
superagent-node-http-timings - 在 node.js 中测量 http 时间
¥superagent-node-http-timings - measure http timings in node.js
-
superagent-cheerio - 自动将 cheerio 添加到你的响应内容中。为 HTML 和 XML 响应主体添加
res.$
。¥superagent-cheerio - add cheerio to your response content automatically. Adds
res.$
for HTML and XML response bodies. -
@certible/superagent-aws-sign - 签署 AWS 端点请求,它使用 aws4 来验证 SuperAgent 请求
¥@certible/superagent-aws-sign - Sign AWS endpoint requests, it uses the aws4 to authenticate the SuperAgent requests
请在你的插件前加上 superagent-*
,以便其他人可以轻松找到它。
¥Please prefix your plugin with superagent-*
so that it can easily be found by others.
对于 SuperAgent 扩展(例如 couchdb 和 oauth),请访问 wiki。
¥For SuperAgent extensions such as couchdb and oauth visit the wiki.
从以前的版本升级
¥Upgrading from previous versions
请参阅 GitHub 发布页面 了解当前更改日志。
¥Please see GitHub releases page for the current changelog.
我们的重大更改主要涉及很少使用的功能和更严格的错误处理。
¥Our breaking changes are mostly in rarely used functionality and from stricter error handling.
-
-
使用
qs
库的arrayFormat: 'indices'
语义,在序列化application/x-www-form-urlencoded
时,浏览器行为更改为匹配 Node。(参见:https://www.npmjs.com/package/qs#stringifying)¥Browser behaviour changed to match Node when serializing
application/x-www-form-urlencoded
, usingarrayFormat: 'indices'
semantics ofqs
library. (See: https://www.npmjs.com/package/qs#stringifying)
-
-
-
重试行为仍是可选的,但是我们现在有更细粒度的状态代码和错误代码列表,我们会针对这些代码进行重试(请参阅更新的文档)
¥Retry behavior is still opt-in, however we now have a more fine-grained list of status codes and error codes that we retry against (see updated docs)
-
修复了 Content-Type 匹配不区分大小写的特定问题
¥A specific issue with Content-Type matching not being case-insensitive is fixed
-
IE 9 现在需要设置,有关更多见解,请参阅 所需的浏览器功能
¥Set is now required for IE 9, see Required Browser Features for more insight
-
-
-
我们已经实现了 Lass 的构建设置以简化我们的堆栈和 linting
¥We've implemented the build setup of Lass to simplify our stack and linting
-
未缩小的浏览器化构建大小已从 48KB 减少到 20KB(通过
tinyify
和使用@babel/preset-env
和.browserslistrc
的最新版本的 Babel)¥Unminified browserified build size has been reduced from 48KB to 20KB (via
tinyify
and the latest version of Babel using@babel/preset-env
and.browserslistrc
) -
已使用
caniuse-lite
和eslint-plugin-compat
添加了 Linting 支持¥Linting support has been added using
caniuse-lite
andeslint-plugin-compat
-
现在我们可以使用
.babelrc
更轻松地定位我们希望支持的 Node 版本¥We can now target what versions of Node we wish to support more easily using
.babelrc
-
-
-
确保你运行的是 Node 6 或更高版本。我们已放弃对 Node 4 的支持。
¥Ensure you're running Node 6 or later. We've dropped support for Node 4.
-
我们已经开始使用 ES6,并且为了与 Internet Explorer 兼容,你可能需要使用 Babel。
¥We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
-
我们建议从
.end()
回调迁移到.then()
或await
。¥We suggest migrating from
.end()
callbacks to.then()
orawait
.
-
-
-
确保你运行的是 Node 4 或更高版本。我们已放弃对 Node 0.x 的支持。
¥Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
-
多次调用
.send()
的测试代码。现在将抛出对.send()
的无效调用,而不是发送垃圾。¥Test code that calls
.send()
multiple times. Invalid calls to.send()
will now throw instead of sending garbage.
-
-
-
如果你在浏览器版本中使用
.parse()
,请将其重命名为.serialize()
。¥If you use
.parse()
in the browser version, rename it to.serialize()
. -
如果你依赖于查询字符串值中的
undefined
被逐字发送为文本 "undefined",请切换到检查缺失值。?key=undefined
现在是?key
(没有值)。¥If you rely on
undefined
in query-string values being sent literally as the text "undefined", switch to checking for missing value instead.?key=undefined
is now?key
(without a value). -
如果你在 Internet Explorer 中使用
.then()
,请确保你有一个添加全局Promise
对象的 polyfill。¥If you use
.then()
in Internet Explorer, ensure that you have a polyfill that adds a globalPromise
object.
-
-
0.x 到 1.x:
¥0.x to 1.x:
-
使用
.then(res => {})
而不是 1 参数回调.end(function(res){})
。¥Instead of 1-argument callback
.end(function(res){})
use.then(res => {})
.
-
贡献者
¥Contributors
名称 |
---|
Kornel Lesiński |
Peter Lyons |
Hunter Loftis |
Nick Baugh |
许可证
¥License
MIT © TJ Holowaychuk