@art-site/art-core-ts-通信状态
当写出HTTP API时,错误处理不需要如此痛苦!
此软件包的用途
任何远程调用——HTTP或其他方式——都可以以数十种不同的方式失败:范围很广的HTTP状态代码,网络错误,超时,用户取消,被禁功能. 但客户只有几种有意义的方法 响应 对于那些失败。 这个软件包的工作是将所有可能的结果的空间倒入客户端实际能够采取的一小组行动.
状态名称只是标签; 动作类别是点。其他一切都是程序员调试的语义.
行动类别
| 状态 | 客户该做什么 |
|---|---|
success | 处理答复 |
pending | 显示进度; 可选择允许取消 |
networkFailure, (中文(简体) ), timeoutFailure | 用后退重试 运输级别问题(包括费率限制、网关超时、DNS/TCP故障)。 只要你退后 自动重试总是安全的. |
serverFailure | 执行者决定 ——服务器侧 逻辑 失败。 操作可能已经完成,也可能没有完成. 对于读取或同源操作:用后退重试. 对于非本能者写道:查询API以检查发生了什么,或表面给用户. |
missing, (中文(简体) ), clientFailure | 别重试 ——请求本身是错误的;在再次尝试之前先改正 |
clientFailureNotAuthorized | 提示用户 —— 认证缺失、 过期或被拒绝; 重新登录或刷新签名 |
aborted | 别重试 - 客户故意取消 |
disabled | 请求被故意关闭;可以继续 |
使用相应的 is* 警卫(isRetryableFailure, (中文(简体) ), isServerFailure, (中文(简体) ), isClientFailure, (中文(简体) ), isClientFailureNotAuthorized等)直接将客户端行为从这些类别中驱动出,而从未检查过原始的HTTP代码.
为什么地位要高于行动类别?
严格地说,你只需要几个动作类别——然而这个库显示的状态大约比这个多出50%。 额外的颗粒性存在,所以客户端可以 日志、警报和升级 即使失败 动作 完全一样.
譬如说, missing (例如404个)和 clientFailure (如:400)两者都属于"不要重试——修正请求",但你几乎肯定想在日志中以不同的方式对待他们:
missing经常被期望——一个用户输入了错误的URL,一个记录被删除——并且通常需要info日志最多clientFailure通常是指 代码 发送了一个错误的请求, 它是一个错误值warn或者说errorserverFailure通常应该比networkFailure- 服务器错误的一分, 碎片运输的一分clientFailureNotAuthorized可能想要自己的安全/审计衡量标准,与一般客户错误分开
认为每个状态为: 动作类别+重度提示。使用动作类别来决定代码 已经; 使用特定状态决定多响度 为: 关于它.
为什么是这个模块?
HTTP 状态代码混淆了两个不同的目的:告诉客户要做什么 对,并传达关于 为什么 有些事失败了 这种双重目的使得客户代码比需要的复杂. 而并不是每个失败都被HTTP所覆盖——网络故障,超时,以及客户端中止完全没有状态代码.
这个图书馆只关注软件可以针对什么而采取行动,从而挑逗了这些关切。 HTTP状态代码加上非HTTP故障模式的全部空间被缩小为可操作的一小类,因此客户端代码可以更简单,更坚固,更安全(例如,从不重试-洗涤有收率限制的终点).
安装和使用示例( 需要)
用 npm 安装 :
npm install @art-suite/art-core-ts-communication-status
基本用途:
import {
isSuccess,
isServerFailure,
success, // === "success"
missing, // === "missing"
} from "@art-suite/art-core-ts-communication-status";
// Handle success
if (isSuccess(status)) {...}
// Simply handle all server failures
if (isServerFailure(status)) {...}
// or Handle multiple statues as a simple switch:
switch (status) {
case success:
/*...*/ break; // Request completed successfully
case missing:
/*...*/ break; // Resource not found, ask the user to fix
default:
/*...*/ break; // handle all other failures as one
}
职能概览
状态类型
状态是字符串,或者可以导入同名常数 :
-
成功 :
success万岁
-
失踪 :
missing—— 说 资源 不存在(3xx重定向,404,410). 注意,这是关于 数据,与请求形状无关——见clientFailure用于不支持的方法/能力.
-
客户端失败( 修正请求或提示用户) :
clientFailure- 请求错误(大多数4xx,加上501,505)clientFailureNotAuthorized失踪/过期/被拒(401 403 407 451 511)
-
服务器端逻辑失败( 可能性问题) :
serverFailure——作业可能已经完成也可能没有完成(500,506-508,510,525,526,530)
-
运输级别故障( 总是安全地使用后退重试):
networkFailure——限速,下关,DNS/TCP/TLS故障(423,425,429,502,503,521,523,527,外加非HTTP运输故障)timeoutFailure——请求超过最后期限(408起,504起,522起,524起,598起,599起,加上客户端暂停)
-
记名状态( 没有错误, 没有成功 ) :
aborted——客户故意取消申请pending请求正在执行中disabled- 有意终止请求(httpstatus 0)
类型警卫
isSuccess(status)——成功isMissing(status)——资源不存在isClientFailure(status)请求本身是错误的(包括认证失败)isClientFailureNotAuthorized(status)特别是认证失败isServerFailure(status)——服务器逻辑故障(机能问题)isNetworkFailure(status)——运输一级故障isTimeout(status)——超时isAborted(status)——客户端被取消isPending(status)——正在进行isDisabled(status)故意离开isFailure(status)- 任何失败isNonClientFailure(status)- 失败不是客户的错isRetryableFailure(status)—— 说 安全可自动重试 (网络故障+有超时故障)
HTTP 状态代码映射
库将HTTP状态代码映射到这些简化状态. 注意它如何不尊重HTTP的先入为主的数组——即是整点:HTTP分散了运输问题,超时,以及跨越4xx和5xx两个范围的速率限制,因此"处理所有5xx相同的"会导致破解的重试逻辑.
| HTTP 代码 | 来文现状 |
|---|---|
0 | disabled |
2xx | success |
3xx, (中文(简体) ), 404, (中文(简体) ), 410 | missing |
401, (中文(简体) ), 403, (中文(简体) ), 407, (中文(简体) ), 451, (中文(简体) ), 511 | clientFailureNotAuthorized |
408, (中文(简体) ), 504, (中文(简体) ), 522, (中文(简体) ), 524, (中文(简体) ), 598, (中文(简体) ), 599 | timeoutFailure |
423, (中文(简体) ), 425, (中文(简体) ), 429, (中文(简体) ), 502, (中文(简体) ), 503, (中文(简体) ), 521, (中文(简体) ), 523, (中文(简体) ), 527 | networkFailure |
501, (中文(简体) ), 505,其他大多数 4xx | clientFailure |
500, (中文(简体) ), 506– 说吧 –508, (中文(简体) ), 510, (中文(简体) ), 525, (中文(简体) ), 526, (中文(简体) ), 530,以及其它 5xx 数据 | serverFailure |
注意:HTTP重定向(3xx)是协议级信号,应由HTTP客户端库处理(后接). 他们被映射到 missing 只有在达到应用代码时 才能作为防御的后退.
API 文档参考
关于所有被输出功能及其参数的详细信息,请参见源代码内的TypeScript打字和JSDoc评论.