节点. JS 云服务客户端
此客户端可用于以javascript提交 HTTP 请求. 你可以问,“为什么使用这个客户端而不是更受欢迎的图书馆?”
首先,它不是为Node.JS重写HTTP功能;它仍然打算与受欢迎的模块一起使用(比如: fetch 或者说 axios用于实际的HTTP处理. 想象客户端更像是在这些模块提供的基本HTTP能力之上所构建的附加功能;在与复杂的云服务通信时,通常需要这些功能.
以下是一些功能:
- 提供可配置的请求重试功能 。 例如,如果HTTP请求以5xx级别出错或与网络相关的出错而失败,客户端会自动重试请求,最多重试一次. 每一次重试 每一次尝试中都要等待更长的时间.
- 提供可配置"波澜"功能. 即使在成功的请求中,客户端也可以被配置来持续地对一个URL进行投票,直到它以理想的方式响应.
- 客户端可以和
axios或者说fetch当前使用fetch并且需要利用客户端的重试功能? 换掉你的fetch与客户端的通话;其他一切(如响应格式,选项等)将无缝地适应. - 当服务器提供Set-Cookie头头时,可以配置处理. 客户端会把这些饼干储存在自己的罐子里,然后用在 其后的请求.
目录
安装
模块可以从 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 。 方法返回 aPromise那个 当客户端的饼干被清除后, 将会解决.- 示例
const { clearCookies } = require('@adobe/cloud-service-client');
- 示例
- {函数}
setGlobalOptions: 使用一个单一的参数,该参数应是任何针对客户的要求选项,以适用于 全部 请客户端发送。 请注意,这仅适用于客户的要求选项,如 请求选项;应该向该职能提供选项,如同它们提供给cloudClient属性。 基础 HTTP 选择库(即.axios或者说fetch)应用于应用其他全球请求级选项.- 示例
const { setGlobalOptions } = require('@adobe/cloud-service-client'); - 用法 :
setGlobalOptions({ eventuallyConsistentCreate: true });
- 示例
选项
客户选项
出口类 axiosClient() 财务报告和审定财务报表 fetchClient() 接受一个可选的第二个参数,该参数应该是一个包含以下任何配置的简单对象:
- {布尔}
handleCookies: 如果true,客户端将利用其饼干处理能力提供"饼干"部分所描述的饼干处理功能. 默认 :false。 。 。 . - {对象}
log: 见 日志 详细情况.
例如:
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: 应返回 aPromise如果客户提供的信息值得重试,则认定属实。 函数将传递一个参数: 由下列属性组成的对象:- {编号} 尝试: 当前请求已发送的次数 .
- 最大尝试 : 默认 客户端选项中提供的尝试次数上限.
- {数} 延迟 : 默认 时间,以毫秒计,客户端应在复试之间延迟.
- {数} 延迟 : 默认 根据客户选项提供的多个选项.
- QQ 回复:响应是请求的结果. 这将是基础HTTP库的原始响应.
- {string} URL: 客户端向它发送生成响应的HTTP请求的URL.
- {object} 选项: 包含给基础的 HTTP 库的原始选项的简单对象 .
- {函数}
getDelay: 应返回 aPromise以毫秒的时间决定客户端在重试请求前的等待时间。 此值将结合延迟多次以指数方式延迟后续重试一起使用. 函数将使用一个单一的参数调用: 匹配在shouldRetry函数。 如果没有指定,该值将默认为客户端重试选项中提供的延迟. - {函数}
getDelayMultiple: 应返回 aPromise在计算重试请求前的延迟时间量时,它决定使用多个。 函数将使用一个单一的参数调用: 匹配在shouldRetry函数。 如果没有指定该值将默认为客户端重试选项中提供的倍数 . - {函数}
getMaxRetries: 应返回 aPromise确定应提出特定请求的最多次数。 函数将使用一个单一的参数调用: 匹配在shouldRetry函数。 如果不指定,该值将默认为客户端重试选项中提供的数字. 请注意:-1表示客户端应继续无限期重试; 在极端谨慎的情况下使用此选项。 。 。 . - {函数}
getRequestOptions: 应返回 aPromise以原始选项解决在下次重试请求时向 HTTP 客户端提供的选项。 这些选项将与最初生成响应的选项合并. 函数将使用一个单一的参数调用: 匹配在shouldRetry函数。 如果没有指定,客户端将使用最初提供的请求选项.
- {函数}
- {数目}
count:客户端将重试给定请求的最大次数. 请注意,这是 默认 价值,不一定会受到所有重试策略的尊重。 默认: 3. - {数目}
delay: 时间量, 以毫秒计, 客户端会在需要重试请求前等. 默认值:1000. - {数目}
delayMultiple:客户端每次延迟重试,都会乘以delay按此值计算。 假设delay1000个,retry是 4 个,而且delayMultiple2. 客户端第一次重审一个要求,它将等待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: 客户端收回回复时间的无九时间戳.
- {Array<对象>
- {对象}
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: 与错误相关的消息.
- {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}你来干什么
请求重试
客户端已内置支持在特定情况下重试特定请求. 这些情况由"要求重试策略"决定. 在概念上,客户有一份战略清单;每项战略负责审查对一项请求的答复,并表明该项请求是否有资格重新试验。 无论何时 客户端提出请求,它会通过其战略清单传递答复。 表示请求应重审的第一个策略会迫使客户端重审请求. 客户端会使用这个算法,无论响应是否可被认为是"成功"还是"失败"
默认情况下,客户端将最多重试一次请求,以指数方式延迟每次重试之间的时间. 然而,这种行为可能被个别策略所压倒.
重试后页眉
如果服务器响应 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请求中提供了标题.
- 使用默认的重试、 延迟和多重重试, 如果响应代码是 200 但响应则重试请求
- 最终一致删除
- 如果响应代码是, 使用默认的重试、 延迟和多次重试请求 没有 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);
实例
看图书馆的 最终合同测试 用于各种如何使用库的例子.
释放
此模块使用 语义释放 当发布新版本时。 合并后即启动这一进程 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.
捐款
欢迎捐款! 读取 贡献指南 更多信息.
许可证发放
这个项目根据Apache V2许可证获得许可. 见 自由主义 更多信息.