# @cplieger/fetch 中文文档

规范地址：https://npmcn.com/package/%40cplieger/fetch/

版本：2\.3\.0
npm 元数据更新时间：2026-11-04T16:27:25.456Z
中文译文更新时间：2026-11-10T21:35:06.412Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cplieger/fetch
原文对照：https://npmcn.com/package/%40cplieger/fetch/?lang=original
项目主页：https://github.com/cplieger/fetch
源码仓库：https://github.com/cplieger/fetch

弃用说明：Moved into @cplieger/ui: import @cplieger/ui/fetch\. Guide: https://github\.com/cplieger/ui/blob/main/docs/migrating\.md

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

- 包体积（解压后）：55.1 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-04T21:33:13.570Z
- 最新版本发布：2026-11-01T13:04:52.270Z
- 近 30 天下载量：3950（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

处理类型Script JSON 请求, 不丢弃, 作为输入结果或数据或数值

## 安装

```sh
npm install @cplieger/fetch
```

也可以使用：`pnpm add @cplieger/fetch`、`yarn add @cplieger/fetch`、`bun add @cplieger/fetch`

## README

# 获取

[![npm](https://img.shields.io/npm/v/@cplieger/fetch)](https://www.npmjs.com/package/@cplieger/fetch) [![JSR](https://jsr.io/badges/@cplieger/fetch)](https://jsr.io/@cplieger/fetch) [![Mutation (TS)](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cplieger/fetch/badges/mutation-ts.json)](https://github.com/cplieger/fetch/issues?q=label%3Astryker-tracker)

`@cplieger/fetch` 覆盖平台 `fetch` 对于 TypeScript , JSON 请求从不掷出 。 每个调用返回一个输入的成功值或错误值,或只返回数据或 `null` 当你需要的就是这些.

它取代了 `try`编号 :`catch`,则 `response.ok` 检查和 `JSON.parse` 否则你每通电话都会写 它没有运行时间依赖和船舶作为只作为无害环境管理的TypeScript源,你的捆绑者用自己的代码编译. 它需要TypeScript 5.0或更晚,并运行于Node 18,Chrome 103,Safari 16和Firefox 100或更晚. 它根据Apache-2.0获得许可.

## 为什么用它

`@cplieger/fetch` 用于前端和服务器的代码,该代码可调用 JSON API ,并想要处理其中的每个失败 `if`。 。 。 .

-   网络故障、 超时、 取消请求、 非-2xx 响应以及 无法验证的机构 都以错误值返回 `code`。 。 。 .
-   失败的反应保持了状态,标题和解析JSON的身体,所以429's `Retry-After` 是一个财产离开.
-   验证是一个简单的函数,所以 Zod 或 valibot schema 插件作为 `(v) => schema.parse(v)`。 。 。 .
-   有了绝对的基础URL,绝对或协议相对路径无法到达另一个来源.
-   它大约是2千B 精密和克齐普, 它的测试 与铬自己的 `fetch`, (中文(简体) ), `Headers` 财务报告和审定财务报表 `AbortSignal`。 。 。 .

考虑 [凯](https://github.com/sindresorhus/ky) 如果您想要在一个客户端中重试、挂钩、上传和下载进度。 考虑 [函数](https://github.com/unjs/ofetch) 如果您需要在节点、浏览器和工人上进行流式响应和自动重试.

## 安装

```sh
npx jsr add @cplieger/fetch
# or
npm i @cplieger/fetch
```

## 使用量

每个后端创建一个实例, 然后在结果上创建分支 :

```typescript
import { createFetch } from "@cplieger/fetch";

export const api = createFetch({ baseUrl: "https://api.example.com/v1" });

const res = await api.apiGetRaw<{ id: string; name: string }>("/users/me");
if (res.ok) {
  console.log(res.data.name, res.headers.get("ETag"));
} else {
  // status is 0 when no response arrived; code says why.
  console.error(res.status, res.code, res.error);
}
```

当您只需要数据时,没有后缀的帮助者返回数据,或者 `null` 任何错误. `apiPost`, (中文(简体) ), `apiPut` 财务报告和审定财务报表 `apiPatch` 发送他们的第二个参数作为 JSON 与 `Content-Type: application/json`数字 :

```typescript
const user = await api.apiGet<{ id: string; name: string }>("/users/me"); // the user, or null
const created = await api.apiPost<{ id: string }>("/items", { name: "widget" });
```

验证一个具有返回已键入值或抛出值的任何函数的响应正体。 抛出一个错误 `code: "decode"`数字 :

```typescript
import { z } from "zod";

const User = z.object({ id: z.string(), name: z.string() });
const user = await api.apiGetTyped("/users/me", (v) => User.parse(v)); // typed, or null
```

每个帮手都要最后的 `options` 对取消信号、超时、额外标题、解码器、预编码机构、跳过成功机构或读取为 `Blob`数字 :

```typescript
const controller = new AbortController();
await api.apiGetRaw("/slow", { signal: controller.signal, timeoutMs: 5_000 });
await api.apiDeleteRaw("/items/1", { ignoreBody: true });
const poster = await api.apiGet("/posters/42", { as: "blob" }); // a Blob, or null
```

在一个地方对每一次失败采取行动,如在会话到期时将用户发送到其中签字,使实例 `onError` 钩. 它看到每一个失败 与它的 `code` 已经从身体上读到, 并且它不扔或返回到呼叫者:

```typescript
export const api = createFetch({
  baseUrl: "https://api.example.com/v1",
  onError: (err) => {
    if (err.status === 401 && err.code === "session_expired") location.assign("/login");
  },
});
```

在路径中设置查询参数, 例如 `/items?page=2`。要添加一个在启动后更改的页眉,例如一个符号,请在实例中读取 `prepareHeaders` 钩子,它运行在每一个请求。 超时开始于 `prepareHeaders` 返回,所以可以挂起的钩子需要自己的限制. [请求、超时和运行时间](https://npmcn.com/package/%40cplieger/fetch/docs/requests.md) 覆盖每个设置和选项.

## API 密码

-   实例 : `createFetch(config?)` 返回 a `FetchInstance`。 。 。 . `FetchConfig` 持有 `baseUrl`, (中文(简体) ), `credentials`, (中文(简体) ), `prepareHeaders`, (中文(简体) ), `fetchFn`, (中文(简体) ), `maxResponseBytes` 财务报告和审定财务报表 `onError`。 。 。 .
-   一次请求: `requestRaw` 财务报告和审定财务报表 `request`附加时 `apiGet`, (中文(简体) ), `apiPost`, (中文(简体) ), `apiPut`, (中文(简体) ), `apiPatch` 财务报告和审定财务报表 `apiDelete` 以简单形式返回数据或 `null` (单位:千美元) `*Raw` 以返回全部结果. `apiGetTyped` 财务报告和审定财务报表 `apiPostTyped` 还取解码器.
-   超时 : `withTimeout(signal, ms)` 财务报告和审定财务报表 `API_TIMEOUT_MS`30,000毫秒(英语:.
-   类型 : `ApiOk<T>`, (中文(简体) ), `ApiErr`, (中文(简体) ), `ApiResult<T>`, (中文(简体) ), `Decoder<T>`, (中文(简体) ), `FailedRequest`, (中文(简体) ), `HttpMethod`, (中文(简体) ), `RequestOptions<T>` jSON读取和 `BlobRequestOptions` 页:1 `as: "blob"`。 。 。 .

全文见 [日 尔](https://jsr.io/@cplieger/fetch/doc)。 。 。 .

## 错误是值

`requestRaw` 和每个 `*Raw` 帮助者决心 `ApiResult<T>` 永远不要扔 一个成功是 `{ ok: true, status, data, headers }`。错误是 `{ ok: false, status, error, code?, requestId?, headers?, body? }`。 。 。 .

`status` 当没有回复时为 0. `code` 那时 `network`, (中文(简体) ), `timeout`, (中文(简体) ), `cancelled` 或者说 `invalid`时 `invalid` 表示请求无法构建且从未发送 。 不是JSON或者解码器故障的2xx尸体是 `decode`真实状态 非-2xx响应保持其状态和标题. 当它的身体是JSON时, `body` 拿着它,还有它的 `error`, (中文(简体) ), `code` 财务报告和审定财务报表 `request_id` 字段填充结果 `error`, (中文(简体) ), `code` 财务报告和审定财务报表 `requestId`。 。 。 .

服务器控制 `code` 发送 `timeout` 或另一个图书馆代码。 图书馆代码随之而来 `status` 0,或 2xx 状态 `decode`,而服务器代码总是随其非-2xx状态而来. 处理 `body` 作为不信任的输入.

一个204或一个空的2xx体给予 `data: undefined`被援助者变成 `null`一个JSON `null`, (中文(简体) ), `0`, (中文(简体) ), `false` 或者说 `""` 是真实的数据.

[结果和错误](https://npmcn.com/package/%40cplieger/fetch/docs/results.md) 有完整的合同.

## 路径停留在您的基址下

绝对的 `baseUrl`,每个请求都会去那个计划和主机。 类似路径 `https://other.example` 或者说 `//host` 成为路径的一部分,所以 `https://api.example.com/v1` 加号 `https://other.example` 请求 `https://api.example.com/v1/https://other.example`A级 `..`,一个点段或一个回击不能从基路径爬出,而查询字符串和片段是按书面发送的.

保护需要 `baseUrl` 有计划 和东道主。 空或相亲 `baseUrl`,一个与协议相对的路径仍然可以到达另一个来源. 没有 `baseUrl`,路径 `fetch()` 不变,所以永远不要通过不信任的输入作为整个路径.

[基础 URL 和不信任的回复](https://npmcn.com/package/%40cplieger/fetch/docs/security-model.md) 覆盖此和响应大小上限 .

## 不支持设计

`@cplieger/fetch` 没有重试或回放、截取链、响应缓存、解码器梳理器、可变或全局设置、自动同位素键或请求ID头,或流式响应. [不支持设计](https://npmcn.com/package/%40cplieger/fetch/docs/non-goals.md) 给出每个理由 以及用什么代替.

## 相关项目

-   [@cplieger/ 动作](https://github.com/cplieger/actions) 以这个库为基础,并添加了备份的再试,请求去dupe,乐观的更新和通知.
-   [httpx 数据](https://github.com/cplieger/httpx) 是 Go 库,用于输出的 HTTP 调用, 并使用复写和备份 .

## 文档

-   [结果和错误](https://npmcn.com/package/%40cplieger/fetch/docs/results.md) 列出每个结果字段、错误代码和空字符规则.
-   [请求、超时和运行时间](https://npmcn.com/package/%40cplieger/fetch/docs/requests.md) 包含实例设置、请求选项、超时和运行时版本.
-   [基础 URL 和不信任的回复](https://npmcn.com/package/%40cplieger/fetch/docs/security-model.md) 解释路径规则,响应大小上限以及如何读取服务器控制的字段.
-   [不支持设计](https://npmcn.com/package/%40cplieger/fetch/docs/non-goals.md) 列出故意遗漏的特性,并说明理由.

## 捐款

欢迎提出问题和拉动请求。 见 [捐款额](https://npmcn.com/package/%40cplieger/fetch/CONTRIBUTING.md)。 。 。 .

## 免责声明

这个项目是精心设计的,遵循安全最佳做法,但打算供个人/自发使用。 不保证生产环境的适宜性. 自己冒险使用.

这个项目是利用AI辅助工具,使用 [克劳德](https://claude.com/), (中文(简体) ), [常规](https://openai.com/),以及 [基罗](https://kiro.dev/)人类维护者界定建筑、监督实施和作出所有最后决定.

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://npmcn.com/package/%40cplieger/fetch/LICENSE)。 。 。 .

## 常见问题

### @cplieger/fetch 是什么？

处理类型Script JSON 请求, 不丢弃, 作为输入结果或数据或数值注意：该包已被作者标记为弃用——Moved into @cplieger/ui: import @cplieger/ui/fetch\. Guide: https://github\.com/cplieger/ui/blob/main/docs/migrating\.md

### 如何安装 @cplieger/fetch？

在项目目录运行 npm install @cplieger/fetch，或使用 pnpm add / yarn add / bun add。

### @cplieger/fetch 支持 TypeScript 吗？

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

### @cplieger/fetch 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cplieger/fetch 可以商用吗？

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

### @cplieger/fetch 的下载量有多少？

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

### @cplieger/fetch 还在维护吗？

最新版本 2\.3\.0 发布于 2026/11/01（9 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/07/05。作者已将其标记为弃用，新项目建议寻找替代方案。