# @adobe/cloud-service-client 中文文档

规范地址：https://npmcn.com/package/%40adobe/cloud-service-client/

版本：2\.0\.1
npm 元数据更新时间：2026-10-01T01:32:36.757Z
中文译文更新时间：2026-11-05T22:19:55.728Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adobe/cloud-service-client
原文对照：https://npmcn.com/package/%40adobe/cloud-service-client/?lang=original
项目主页：https://github.com/adobe/cloud-service-client#readme
源码仓库：https://github.com/adobe/cloud-service-client

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：362 kB，33 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.20\.3
- 运行依赖：3 个
- 首次发布：2022-11-18T21:52:01.909Z
- 最新版本发布：2026-06-10T16:24:08.191Z
- 近 30 天下载量：12912（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

使用基于 HTTP 的云服务工作的客户端

## 安装

```sh
npm install @adobe/cloud-service-client
```

也可以使用：`pnpm add @adobe/cloud-service-client`、`yarn add @adobe/cloud-service-client`、`bun add @adobe/cloud-service-client`

## README

# 节点. JS 云服务客户端

[![build status](https://github.com/adobe/cloud-service-client/actions/workflows/node.js.yml/badge.svg)](https://github.com/adobe/cloud-service-client/actions/workflows/node.js.yml) [![Node version](https://img.shields.io/npm/v/@adobe/cloud-service-client)](https://www.npmjs.com/package/@adobe/cloud-service-client/)

此客户端可用于以javascript提交 HTTP 请求. 你可以问,“为什么使用这个客户端而不是更受欢迎的图书馆?” 首先,它不是为Node.JS重写HTTP功能;它仍然打算与受欢迎的模块一起使用(比如: `fetch` 或者说 `axios`用于实际的HTTP处理. 想象客户端更像是在这些模块提供的基本HTTP能力之上所构建的附加功能;在与复杂的云服务通信时,通常需要这些功能. 以下是一些功能:

-   提供可配置的请求重试功能 。 例如,如果HTTP请求以5xx级别出错或与网络相关的出错而失败,客户端会自动重试请求,最多重试一次. 每一次重试 每一次尝试中都要等待更长的时间.
-   提供可配置"波澜"功能. 即使在成功的请求中,客户端也可以被配置来持续地对一个URL进行投票,直到它以理想的方式响应.
-   客户端可以和 `axios` 或者说 `fetch`当前使用 `fetch` 并且需要利用客户端的重试功能? 换掉你的 `fetch` 与客户端的通话;其他一切(如响应格式,选项等)将无缝地适应.
-   当服务器提供Set-Cookie头头时,可以配置处理. 客户端会把这些饼干储存在自己的罐子里,然后用在 其后的请求.

## 目录

-   [节点. JS 云服务客户端](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-nodejs-cloud-service-client)
    -   [目录](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-contents)
    -   [安装](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-installation)
    -   [使用量](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-usage)
        -   [轴使用](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-axios-usage)
        -   [获取使用](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-fetch-usage)
        -   [额外出口](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-additional-exports)
    -   [选项](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-options)
        -   [客户选项](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-client-options)
        -   [请求选项](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-request-options)
    -   [回应](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-response)
    -   [请求重试](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-request-retry)
        -   [重试后页眉](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-retry-after-header)
        -   [示例重试策略](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-example-retry-strategies)
        -   [内建重试策略](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-built-in-retry-strategies)
    -   [饼干](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-cookies)
    -   [日志](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-logging)
        -   [设置日志级别](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-set-a-log-level)
        -   [提供自定义记录器](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-provide-a-custom-logger)
    -   [实例](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-examples)
-   [释放](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-releasing)
-   [捐款](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-contributing)
-   [许可证发放](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-licensing)

## 安装

模块可以从 npm 安装 :

```
npm install @adobe/cloud-service-client
```

## 使用量

以下是如何使用客户端的一些例子.

### 轴使用

```
const originalAxios = require('axios');
const { axiosClient } = require('@adobe/cloud-service-client');

// add client functionality to axios
const axios = axiosClient(originalAxios);

// submit a request that will behave like axios:
const response = await axios('http://myrequesturl.com');

// the response will follow axios' response schema:
const {
  data,
  status,
  statusText,
  headers
} = response;

// axios' other methods work as well:
const response = await axios.get('http://myrequesturl.com);

// pass in any of axios' options:
const response = await axios({
  url: 'http://myrequesturl.com',
  method: 'get',
  responseType: 'stream'
});
```

### 获取使用

```
const nodeFetch = require('node-fetch');
const { fetchClient } = require('@adobe/cloud-service-client');

// add client functionality to node-fetch
const fetch = fetchClient(nodeFetch);

// submit the request as fetch would
const response = await fetch('http://myrequesturl.com');

// the response will follow fetch's schema:
const {
  status,
  statusText,
  headers
} = response;
const header1 = headers.get('my-header);
const data = await response.json();

if (response.ok) {
  // process successful response
}

// pass in any of fetch's options:
const response = await fetch('http://myrequesturl.com', {
  method: 'get',
  mode: 'cors',
  redirect: 'follow'
});
```

### 额外出口

除了提供与正在使用的HTTP库相同的导出外,客户端还提供以下功能:

-   {函数} `clearCookies`: 当引用时, 清除当前客户端可能存储的任何 cookie 。 方法返回 a `Promise` 那个 当客户端的饼干被清除后, 将会解决.
    -   示例 `const { clearCookies } = require('@adobe/cloud-service-client');`
-   {函数} `setGlobalOptions`: 使用一个单一的参数,该参数应是任何针对客户的要求选项,以适用于 _全部_ 请客户端发送。 请注意,这仅适用于客户的要求选项,如 [请求选项](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-request-options);应该向该职能提供选项,如同它们提供给 `cloudClient` 属性。 基础 HTTP 选择库(即. `axios` 或者说 `fetch`)应用于应用其他全球请求级选项.
    -   示例 `const { setGlobalOptions } = require('@adobe/cloud-service-client');`
    -   用法 : `setGlobalOptions({ eventuallyConsistentCreate: true });`

## 选项

### 客户选项

出口类 `axiosClient()` 财务报告和审定财务报表 `fetchClient()` 接受一个可选的第二个参数,该参数应该是一个包含以下任何配置的简单对象:

-   {布尔} `handleCookies`: 如果 `true`,客户端将利用其饼干处理能力提供"饼干"部分所描述的饼干处理功能. 默认 : `false`。 。 。 .
-   {对象} `log`: 见 [日志](https://npmcn.com/package/%40adobe/cloud-service-client/#readme-logging) 详细情况.

例如:

```
const axios = axiosClient(originalAxios, {
  handleCookies: true,
});
```

### 请求选项

除了得到支持的任何选项之外 `axios` 或者说 `fetch`,客户端有自己的一些请求选项。 这些选项均应在以下文件中提供: `cloudClient` 属性在请求的配置中。 例如:

```
fetch(url, {
  method: 'POST',
  mode: 'cors',
  cloudClient: {
    timeout: 10000,
    eventuallyConsistentCreate: true
  }
});
```

-   {数目} `timeout`: 客户端在中止前等待请求的时间, 以毫秒计 。 默认情况下,一个被中止的请求符合重试的条件,因此超时请求将适合客户端重试功能.
-   {对象} `retry`:关于客户在某些情况下如何重试请求的各种信息.
    -   {箭头} `strategies`:在确定相应请求是否需要再审之前,重试客户端会发送回复的"策略". 更多信息和实例,请参见"再试"部分. 请注意,这些战略将 _此外,还有:_ 到客户端的默认策略,将重试于出乎意料的网络相关错误或5xx级别状态代码. 阵列中的每个项目应是一个由下列属性组成的战略对象:
        -   {函数} `shouldRetry`: 应返回 a `Promise` 如果客户提供的信息值得重试,则认定属实。 函数将传递一个参数: 由下列属性组成的对象:
            -   {编号} 尝试: 当前请求已发送的次数 .
            -   最大尝试 : _默认_ 客户端选项中提供的尝试次数上限.
            -   {数} 延迟 : _默认_ 时间,以毫秒计,客户端应在复试之间延迟.
            -   {数} 延迟 : _默认_ 根据客户选项提供的多个选项.
            -   QQ 回复:响应是请求的结果. 这将是基础HTTP库的原始响应.
            -   {string} URL: 客户端向它发送生成响应的HTTP请求的URL.
            -   {object} 选项: 包含给基础的 HTTP 库的原始选项的简单对象 .
        -   {函数} `getDelay`: 应返回 a `Promise` 以毫秒的时间决定客户端在重试请求前的等待时间。 此值将结合延迟多次以指数方式延迟后续重试一起使用. 函数将使用一个单一的参数调用: 匹配在 `shouldRetry` 函数。 如果没有指定,该值将默认为客户端重试选项中提供的延迟.
        -   {函数} `getDelayMultiple`: 应返回 a `Promise` 在计算重试请求前的延迟时间量时,它决定使用多个。 函数将使用一个单一的参数调用: 匹配在 `shouldRetry` 函数。 如果没有指定该值将默认为客户端重试选项中提供的倍数 .
        -   {函数} `getMaxRetries`: 应返回 a `Promise` 确定应提出特定请求的最多次数。 函数将使用一个单一的参数调用: 匹配在 `shouldRetry` 函数。 如果不指定,该值将默认为客户端重试选项中提供的数字. 请注意: `-1` 表示客户端应继续无限期重试; _在极端谨慎的情况下使用此选项_。 。 。 .
        -   {函数} `getRequestOptions`: 应返回 a `Promise` 以原始选项解决在下次重试请求时向 HTTP 客户端提供的选项。 这些选项将与最初生成响应的选项合并. 函数将使用一个单一的参数调用: 匹配在 `shouldRetry` 函数。 如果没有指定,客户端将使用最初提供的请求选项.
    -   {数目} `count`:客户端将重试给定请求的最大次数. 请注意,这是 _默认_ 价值,不一定会受到所有重试策略的尊重。 默认: 3.
    -   {数目} `delay`: 时间量, 以毫秒计, 客户端会在需要重试请求前等. 默认值:1000.
    -   {数目} `delayMultiple`:客户端每次延迟重试,都会乘以 `delay` 按此值计算。 假设 `delay` 1000个, `retry` 是 4 个,而且 `delayMultiple` 2. 客户端第一次重审一个要求,它将等待1000ms,第二次等待2000ms,第三次等待4000ms等. 请注意: 这是 _默认_ 价值,不一定会受到所有重试策略的尊重。 默认: 2.
-   {布尔} `eventuallyConsistentCreate`: 当 `true`,客户端将使用内置重试策略,在最终一致的系统中处理创建. 详见"回想"部分. 默认 : `false`。 。 。 .
-   {布尔} `eventuallyConsistentUpdate`: 当 `true`,客户端将使用内置重试策略来处理最终一致系统中的更新. 详见"回想"部分. 默认 : `false`。 。 。 .
-   {布尔} `eventuallyConsistentDelete`: 当 `true`,客户端将使用内置重试策略来处理最终一致系统中的删除. 详见"回想"部分. 默认 : `false`。 。 。 .

## 回应

客户端将扩展由 HTTP 库提供的 HTTP 响应 `cloudClient` 属性。 有关该财产的补充资料如下:

-   {数目} `status`: 响应状态代码. 注意,如果请求未产生响应(如超时出错或一般与网络相关的出错),此值可能缺失.
-   {数目} `statusText`: 答复的现状。 注意,如果请求未产生响应(如超时出错或一般与网络相关的出错),此值可能缺失.
-   {数目} `requestTime`: 基本 HTTP 库提交请求并收到回复的时间, 以毫秒计 。 请注意这将适用于: _最后一个_ 请求已发出。 如果请求有时间, 值可能会丢失 无法确定.
-   {对象} `headers`: 简单对象,其键为头名而值为头名. 这些是答复中提供的HTTP头.
-   {对象} `options`: 启动请求时向客户提供的选项。 对象将有一个 `cloudClient` 财产(无论最初是否提供),加上以下附加财产:
    -   {Array<对象> `retryResponses`:如果对请求进行了再审,则按顺序列出每次答复的清单,从而导致重审. 清单上的每个项目都将包括本节所包括的所有项目,以便重新研究答复.
    -   {数目} `retries`: 答复前的重复次数.
    -   {数目} `retryWait`: 客户端在回复前在复试之间所花的时间, 以毫秒计.
    -   {数目} `startTime`: 请求启动时间的无九时间戳.
    -   {数目} `endTime`: 客户端收回回复时间的无九时间戳.
-   {对象} `error`: 包含关于基础 HTTP 库可能提供的错误信息的简单对象. 此属性只有在出现错误时才会存在,其内容可能因所抛出的错误而异. 如果 错误是已知的javascript 错误类型,它包含以下属性:
    -   {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么 `name`:错误的名称.
    -   {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么 `message`: 与错误相关的消息.

## 请求重试

客户端已内置支持在特定情况下重试特定请求. 这些情况由"要求重试策略"决定. 在概念上,客户有一份战略清单;每项战略负责审查对一项请求的答复,并表明该项请求是否有资格重新试验。 无论何时 客户端提出请求,它会通过其战略清单传递答复。 表示请求应重审的第一个策略会迫使客户端重审请求. 客户端会使用这个算法,无论响应是否可被认为是"成功"还是"失败"

默认情况下,客户端将最多重试一次请求,以指数方式延迟每次重试之间的时间. 然而,这种行为可能被个别策略所压倒.

### 重试后页眉

如果服务器响应 `Retry-After` 页眉,客户端将使用该值高于所有其他重试选项. 例如,假设客户端已被配置为延迟 复试相隔一秒, 延迟多为 2; 当服务器响应时 `Retry-After` 在第二次重试时, 客户端将忽略延迟和 延后多时并等5秒.

这仍然可以克服 通过 `shouldRetry` 方法,它将接收服务器的 `Retry-After` 值为默认延迟.

在后续的重试中, 如果服务器不提供额外信息, 客户端会回到默认行为 `Retry-After` 头.

### 示例重试策略

下列客户端将重试请求, 如果响应代码为 5 次 `404`数字 :

```
axios({
  url: 'http://myurltorequest',
  cloudClient: {
    retry: {
      count: 4,
      strategies: [{
        shouldRetry: async ({ response }) => response.status === 404
      }]
    }
  }
});
```

这个客户端会投票一个 URL,只要响应代码是 `202`,等待着 _不变_ 每次请求之间的时间:

```
axios({
  url: 'http://myurltorequest',
  cloudClient: {
    retry: {
      strategies: [{
        shouldRetry: async ({ response }) => response.status === 202,
        getDelayMultiple: async () => 1,
        getMaxRetries: async () => -1,
      }]
    }
  }
});
```

(对这样的设定要非常小心,因为客户会无限期地投票)

### 内建重试策略

默认情况下,客户端总是会重试由于网络相关问题而失败的请求,或者有5xx级别响应代码的请求.

此外,客户端提供以下可选策略. 注意:"Eventually Conference"是指在远程系统被修改时和在系统中反映上述修改时之间可能存在延迟的概念.

-   最终一致创建
    -   如果响应代码为404,则使用默认重试、延迟和多重试重试请求.
-   最终一致更新
    -   使用默认的重试、 延迟和多重重试, 如果响应代码是 200 但响应则重试请求 `etag` 信头不匹配 `if-match` 请求中提供了标题.
-   最终一致删除
    -   如果响应代码是, 使用默认的重试、 延迟和多次重试请求 _没有_ 404号.

参见如何利用这些战略的重新探索方案.

## 饼干

如果这样配置,客户端就有一些基本的 cookie 处理到位. 例如,如果客户处理的答复有: `Set-Cookie` 标题,客户端会缓存这些 cookie 并将其包含在它随后发出的任何请求中. 注意饼干被设定为客户案例的寿命范围 - 它们不是 持续,一旦客户超出范围,就会丢失.

客户端会倾向于在请求选项中通过的cookie,而不是它所储存的任何cookie. 例如,假设客户端正在存储 cookie `mycookie` 值为 `set-cookie-value` 因为它收到在一个 `Set-Cookie` 头曰. 并假设消费者 客户端通过同样的饼干 `Cookie` 数值为 `options-cookie-value` 当启动请求时。 在这种情况下,客户端会使用 `options-cookie-value` 作为 `mycookie`,因为它被传递到请求选项中.

指定的饼干 `Set-Cookie` 将遵循标题的 HTTP 规格,并将尊重诸如 `Path`, (中文(简体) ), `Domain`, (中文(简体) ), `Max-Age`, (中文(简体) ), `Expires`, (中文(简体) ), `Secure`等 (中文(简体) ). 主要的偏离之处是饼干的生命会 _永远_ 最多是客户范围.

只有在 `handleCookies` 选项是 `true`。 。 。 .

## 日志

客户端将在整个请求过程中记录不同级别的信息. 默认情况下,这些消息不会在任何地方出现;使用以下方法之一改变行为.

### 设置日志级别

设置一个名为环境变量 `NODE_HTTP_CLIENT_LOG_LEVEL` 达到理想的伐木水平。 有效值为 `DEBUG`, (中文(简体) ), `INFO`, (中文(简体) ), `WARN`,或 `ERROR`。 。 。 .

当使用此记录机制时, 所有信件都会写入 `console.log()`。使用自定义日志方法来改变这种行为.

### 提供自定义记录器

使用 `log` 选项以提供您所选择的日志 :

```
const axiosOriginal = require('axios');
const { axiosClient } = require('@adobe/cloud-service-client');

const axios = axiosClient(axiosOriginal, {
  log: {
    debug: () => {},
    info: () => {},
    warn: () => {},
    error: () => {},
  }
});

const response = await axios('http://myrequesturl.com',);
```

如示例所示,提供的伐木机必须具备以下方法:

-   `debug()`
-   `info()`
-   `warn()`
-   `error()`

客户端使用每种方法在相应的日志级别上记录一个消息. 该方法将接收多个参数,性质类似于如何 `console.log()` 可能会被使用。 以下是一些可能的例子:

```
log.debug('simple message');
log.info('formatted message with value %s', formatValue);
log.error('non-formatted message with value', someValue);
```

## 实例

看图书馆的 [最终合同测试](https://npmcn.com/package/%40adobe/cloud-service-client/e2e/all-methods.test.js) 用于各种如何使用库的例子.

# 释放

此模块使用 [语义释放](https://github.com/semantic-release/semantic-release) 当发布新版本时。 合并后即启动这一进程 `main` 树枝。 详细审查语义发布文件,但最常用的公约有:

-   `feat:` 用于含有新特性的非破解释放。 这将增加小版本号。 示例
    -   `feat: <message describing changes>`
    -   假设库当前版本是 `1.2.1`,带有类似上述信息的承诺将触发一个新的发布,其版本号将是: `1.3.0`。 。 。 .
-   `fix:` 用于包含错误修正的非破解释放。 这将增加构建版号。 示例
    -   `fix: <message describing changes>`
    -   假设库当前版本是 `1.2.1`,带有类似上述信息的承诺将触发一个新的发布,其版本号将是: `1.2.2`。 。 。 .

其消息不符合语义-放出格式的PR不会产生新的放出.

发布注释基于 git 承诺消息生成. 发布注释会出现在 ChangeGELOG.md.

# 捐款

欢迎捐款! 读取 [贡献指南](https://npmcn.com/package/%40adobe/cloud-service-client/CONTRIBUTING.md) 更多信息.

# 许可证发放

这个项目根据Apache V2许可证获得许可. 见 [自由主义](https://npmcn.com/package/%40adobe/cloud-service-client/LICENSE.txt) 更多信息.

## 常见问题

### @adobe/cloud-service-client 是什么？

使用基于 HTTP 的云服务工作的客户端

### 如何安装 @adobe/cloud-service-client？

在项目目录运行 npm install @adobe/cloud-service-client，或使用 pnpm add / yarn add / bun add。

### @adobe/cloud-service-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adobe\_\_cloud-service-client 是否存在。

### @adobe/cloud-service-client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adobe/cloud-service-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.20\.3。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adobe/cloud-service-client 可以商用吗？

@adobe/cloud-service-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adobe/cloud-service-client 的下载量有多少？

根据 npm 官方下载统计，@adobe/cloud-service-client 在 2026/10/05 – 2026/11/03 这 30 天内被下载 12,912 次，日均约 430 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adobe/cloud-service-client 还在维护吗？

最新版本 2\.0\.1 发布于 2026/06/11（4 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 1 个；首次发布于 2022/11/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。