# @art-suite/art-core-ts-communication-status 中文文档

规范地址：https://npmcn.com/package/%40art-suite/art-core-ts-communication-status/

版本：0\.12\.1
npm 元数据更新时间：2026-06-19T10:21:59.390Z
中文译文更新时间：2026-11-06T20:37:18.049Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40art-suite/art-core-ts-communication-status
原文对照：https://npmcn.com/package/%40art-suite/art-core-ts-communication-status/?lang=original
项目主页：https://github.com/art-suite/art-suite-ts#readme
源码仓库：https://github.com/art-suite/art-suite-ts

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

- 包体积（解压后）：211 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-05-22T08:45:50.956Z
- 最新版本发布：2026-06-19T10:21:59.259Z
- 近 30 天下载量：3240（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 13 个）

## 中文简介

TypeScript 字符串工具库

## 安装

```sh
npm install @art-suite/art-core-ts-communication-status
```

也可以使用：`pnpm add @art-suite/art-core-ts-communication-status`、`yarn add @art-suite/art-core-ts-communication-status`、`bun add @art-suite/art-core-ts-communication-status`

## README

# @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` 或者说 `error`
-   `serverFailure` 通常应该比 `networkFailure` - 服务器错误的一分, 碎片运输的一分
-   `clientFailureNotAuthorized` 可能想要自己的安全/审计衡量标准,与一般客户错误分开

认为每个状态为: **动作类别+重度提示**。使用动作类别来决定代码 _已经_; 使用特定状态决定多响度 _为:_ 关于它.

## 为什么是这个模块?

HTTP 状态代码混淆了两个不同的目的:告诉客户要做什么 _对_,并传达关于 _为什么_ 有些事失败了 这种双重目的使得客户代码比需要的复杂. 而并不是每个失败都被HTTP所覆盖——网络故障,超时,以及客户端中止完全没有状态代码.

这个图书馆只关注软件可以针对什么而采取行动,从而挑逗了这些关切。 HTTP状态代码加上非HTTP故障模式的全部空间被缩小为可操作的一小类,因此客户端代码可以更简单,更坚固,更安全(例如,从不重试-洗涤有收率限制的终点).

## 安装和使用示例( 需要)

用 npm 安装 :

```sh
npm install @art-suite/art-core-ts-communication-status
```

基本用途:

```ts
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评论.

## 常见问题

### @art-suite/art-core-ts-communication-status 是什么？

TypeScript 字符串工具库

### 如何安装 @art-suite/art-core-ts-communication-status？

在项目目录运行 npm install @art-suite/art-core-ts-communication-status，或使用 pnpm add / yarn add / bun add。

### @art-suite/art-core-ts-communication-status 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @art-suite/art-core-ts-communication-status 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @art-suite/art-core-ts-communication-status 可以商用吗？

@art-suite/art-core-ts-communication-status 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @art-suite/art-core-ts-communication-status 的下载量有多少？

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

### @art-suite/art-core-ts-communication-status 还在维护吗？

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