# @happy-ts/fetch-t 中文文档

规范地址：https://npmcn.com/package/%40happy-ts/fetch-t/

版本：1\.10\.0
npm 元数据更新时间：2026-05-25T08:01:05.740Z
中文译文更新时间：2026-11-17T14:49:02.457Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：188 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-05-09T10:57:41.676Z
- 最新版本发布：2026-05-25T08:01:05.387Z
- 近 30 天下载量：4791（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 12 个）

## 中文简介

类型安全获取 API 包,包含可中止请求,超时支持,进度跟踪,自动重试,以及类似 Rust-Enterpress 错误处理等内容.

## 安装

```sh
npm install @happy-ts/fetch-t
```

也可以使用：`pnpm add @happy-ts/fetch-t`、`yarn add @happy-ts/fetch-t`、`bun add @happy-ts/fetch-t`

## README

# 获取T

[![License](https://img.shields.io/npm/l/@happy-ts/fetch-t.svg)](https://npmcn.com/package/%40happy-ts/fetch-t/LICENSE) [![Build Status](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml/badge.svg)](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/JiangJie/fetch-t/graph/badge.svg)](https://codecov.io/gh/JiangJie/fetch-t) [![NPM version](https://img.shields.io/npm/v/@happy-ts/fetch-t.svg)](https://npmjs.org/package/@happy-ts/fetch-t) [![NPM downloads](https://badgen.net/npm/dm/@happy-ts/fetch-t)](https://npmjs.org/package/@happy-ts/fetch-t) [![JSR Version](https://jsr.io/badges/@happy-ts/fetch-t)](https://jsr.io/@happy-ts/fetch-t) [![JSR Score](https://jsr.io/badges/@happy-ts/fetch-t/score)](https://jsr.io/@happy-ts/fetch-t/score)

类型安全获取 API 包,包含可中止请求,超时支持,进度跟踪,自动重试,以及类似 Rust-Enterpress 错误处理等内容.

* * *

[页:1](https://npmcn.com/package/%40happy-ts/fetch-t/README.cn.md) | [API 文档](https://jiangjie.github.io/fetch-t/)

* * *

## 特征

-   **可中止的请求** - 随时通过 `FetchTask.abort()`
-   **类型安全对策** - 指定返回类型 `responseType` 参数(`text`, (中文(简体) ), `json`, (中文(简体) ), `arraybuffer`, (中文(简体) ), `bytes`, (中文(简体) ), `blob`, (中文(简体) ), `stream`(中文(简体) )
-   **超时支持** - 指定毫秒后自动执行请求
-   **进展跟踪** - 监控下载进度 `onProgress` 回调
-   **串流** - 通过原始数据块访问 `onChunk` 回调
-   **自动重试** - 可配置的重试策略 `retry` 选项
-   **结果错误处理** - 烂透了 `Result` 用于明确错误处理的类型
-   **跨平台** - 与Deno、Node.js、Bun和浏览器合作

## 安装

```sh
# npm
npm install @happy-ts/fetch-t

# yarn
yarn add @happy-ts/fetch-t

# pnpm
pnpm add @happy-ts/fetch-t

# JSR (Deno)
deno add @happy-ts/fetch-t

# JSR (Bun)
bunx jsr add @happy-ts/fetch-t
```

## 快速启动

### 基本用途

```ts
import { fetchT } from '@happy-ts/fetch-t';

// GET JSON data
const result = await fetchT<{ id: number; title: string }>('https://api.example.com/data', {
    responseType: 'json',
});

result.inspect(data => {
    console.log(data.title);
}).inspectErr(err => {
    console.error('Request failed:', err.message);
});
```

### 可中止的请求

```ts
const task = fetchT('https://api.example.com/large-file', {
    abortable: true,
    responseType: 'arraybuffer',
});

// Abort after 5 seconds
setTimeout(() => {
    task.abort('User cancelled');
}, 5000);

const result = await task.result;
```

### 自动重试

```ts
const result = await fetchT('https://api.example.com/data', {
    retry: {
        retries: 3,
        delay: (attempt) => Math.min(1000 * Math.pow(2, attempt - 1), 10000),
        when: [500, 502, 503, 504],
        onRetry: (error, attempt) => console.log(`Retry ${attempt}: ${error.message}`),
    },
    responseType: 'json',
});
```

## 实例

-   [基础](https://npmcn.com/package/%40happy-ts/fetch-t/examples/basic.ts) - 基本获取请求
-   [进展跟踪](https://npmcn.com/package/%40happy-ts/fetch-t/examples/with-progress.ts) - 下载进度和块流
-   [可中止](https://npmcn.com/package/%40happy-ts/fetch-t/examples/abortable.ts) - 取消和暂停请求
-   [重试](https://npmcn.com/package/%40happy-ts/fetch-t/examples/with-retry.ts) - 自动重试策略
-   [处理错误](https://npmcn.com/package/%40happy-ts/fetch-t/examples/error-handling.ts) - 处理模式出错

## 处理错误设计

`fetchT` 区分两类错误:

### 编程出错( 同步)

无效的参数会立即抛出故障快速行为 :

```ts
// These throw synchronously - no try/catch around await needed
fetchT('https://example.com', { timeout: -1 });     // Error: timeout must be > 0
fetchT('https://example.com', { timeout: 'bad' });  // TypeError: timeout must be a number
fetchT('not-a-url');                                // TypeError: Invalid URL
```

这跟本地不同 `fetch`,它返回拒绝的参数错误承诺。 同步抛出能提供更清晰的堆栈痕迹,并在开发过程中捕捉到bug.

### 运行时出错( 结果类型)

网络失败和 HTTP 错误被包入 `Result` 类型 :

```ts
const result = await fetchT('https://api.example.com/data', { responseType: 'json' });

if (result.isErr()) {
    const error = result.unwrapErr();
    // FetchError with status code, or network Error
}
```

## 许可证

[麻省理工学院](https://npmcn.com/package/%40happy-ts/fetch-t/LICENSE)

## 常见问题

### @happy-ts/fetch-t 是什么？

类型安全获取 API 包,包含可中止请求,超时支持,进度跟踪,自动重试,以及类似 Rust-Enterpress 错误处理等内容\.

### 如何安装 @happy-ts/fetch-t？

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

### @happy-ts/fetch-t 支持 TypeScript 吗？

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

### @happy-ts/fetch-t 支持 ESM 还是 CommonJS？

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

### @happy-ts/fetch-t 可以商用吗？

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

### @happy-ts/fetch-t 的下载量有多少？

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

### @happy-ts/fetch-t 还在维护吗？

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

