Skip to main content

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).

此模块的浏览器就绪版本可通过 jsdelivrunpkg 获得,也可在 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

如果你使用的是 browserifywebpackrollup 或其他打包器,那么你可以遵循与上述 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-*,以便其他人可以轻松找到它。

¥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.

  • 6.0 到 6.1

    ¥6.0 to 6.1

  • 5.x 到 6.x

    ¥5.x to 6.x:

    • 重试行为仍是可选的,但是我们现在有更细粒度的状态代码和错误代码列表,我们会针对这些代码进行重试(请参阅更新的文档)

      ¥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

  • 4.x 到 5.x

    ¥4.x to 5.x:

    • 我们已经实现了 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-liteeslint-plugin-compat 添加了 Linting 支持

      ¥Linting support has been added using caniuse-lite and eslint-plugin-compat

    • 现在我们可以使用 .babelrc 更轻松地定位我们希望支持的 Node 版本

      ¥We can now target what versions of Node we wish to support more easily using .babelrc

  • 3.x 到 4.x

    ¥3.x to 4.x:

    • 确保你运行的是 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() or await.

  • 2.x 到 3.x

    ¥2.x to 3.x:

    • 确保你运行的是 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.

  • 1.x 到 2.x

    ¥1.x to 2.x:

    • 如果你在浏览器版本中使用 .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 global Promise 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