# @edgefirst-dev/api-client 中文文档

规范地址：https://npmcn.com/package/%40edgefirst-dev/api-client/

版本：0\.3\.0
npm 元数据更新时间：2025-09-01T23:47:15.658Z
中文译文更新时间：2026-11-13T06:43:45.672Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：21.1 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2024-10-13T23:35:07.173Z
- 最新版本发布：2025-09-01T23:47:15.220Z
- 近 30 天下载量：2216（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

用于提出 API 请求的基本 HTTP 客户端

## 安装

```sh
npm install @edgefirst-dev/api-client
```

也可以使用：`pnpm add @edgefirst-dev/api-client`、`yarn add @edgefirst-dev/api-client`、`bun add @edgefirst-dev/api-client`

## README

# @ dedgefirst-dev/api-客户端

这个 `APIClient` class 提供灵活而可扩展的 HTTP 客户端,用于提出 API 请求. 它支持常见的HTTP方法(`GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT`, (中文(简体) ), `PATCH`, (中文(简体) ), `DELETE`并允许通过 `before` 财务报告和审定财务报表 `after` 截取钩.

## 安装

```sh
bun add @edgefirst-dev/api-client
```

## 使用量

导入 `APIClient` ,并创建一个新实例来提出 API 请求.

```ts
import { APIClient } from "@edgefirst-dev/api-client";

let client = new APIClient("https://api.example.com");
let response = await client.get("/users/1");
```

### 自定义

您可以通过扩展 : `APIClient` 阶级和压倒性 `before` 财务报告和审定财务报表 `after` 方法。 。 .

```ts
class CustomAPIClient extends APIClient {
  async before(request: Request) {
    // Add a custom header to the request
    request.headers.set("X-Custom-Header", "value");

    return request;
  }

  async after(request: Request, response: Response) {
    if (response.status === 401) {
      // Handle unauthorized error
      throw new Error("Unauthorized");
    }

    return response;
  }
}

let client = new CustomAPIClient("https://api.example.com");
let response = await client.get("/users/1");
```

也可以定义子类中的自定义方法来封装常见的API调用.

```ts
import { ObjectParser } from "@edgefirst-dev/data/parser";

class CustomAPIClient extends APIClient {
  async fetchUserData(id: number) {
    let response = await this.get(`/users/${id}`);
    let data = await response.json();
    return new ObjectParser(data);
  }
}

let client = new CustomAPIClient("https://api.example.com");
let user = await client.fetchUserData(1);
let userName = user.string("name");
```

通过压倒构造器,您可以提供默认的基础 URL .

```ts
class CustomAPIClient extends APIClient {
  constructor() {
    super("https://api.example.com");
  }
}

let client = new CustomAPIClient();
```

### 拦截

你可以增加拦截器 `APIClient` 实例来定制请求和响应处理.

```ts
let client = new APIClient("https://api.example.com");

client.interceptors.before.on(async (request) => {
  // Add a custom header to the request
  request.headers.set("X-Custom-Header", "value");

  return request;
});

client.interceptors.after.on(async (request, response) => {
  if (response.status === 401) {
    // Handle unauthorized error
    throw new Error("Unauthorized");
  }

  return response;
});
```

也可以使用 `off` 方法.

```ts
async function beforeInterceptor(request) {
  // Add a custom header to the request
  request.headers.set("X-Custom-Header", "value");

  return request;
}

let client = new APIClient("https://api.example.com");

client.interceptors.before.on(beforeInterceptor); // Add the interceptor
client.interceptors.before.off(beforeInterceptor); // Remove the interceptor
```

子类拦截器在实例拦截器之前运行.

```ts
class CustomAPIClient extends APIClient {
  async before(request: Request) {
    // Add a custom header to the request
    request.headers.set("X-Custom-Header", "1");

    return request;
  }
}

let client = new CustomAPIClient("https://api.example.com");

client.interceptors.before.on(async (request) => {
  // Add a custom header to the request
  request.headers.set("X-Custom-Header", "2");

  return request;
});
```

给 `X-Custom-Header` 将设定为 `2` 在请求中,因为实例截取器覆盖了子类截取器设定的头部.

### 测试

您可以轻松地测试您的 API 通话 `APIClient` 与 [质量](https://mswjs.io/) 来嘲笑API的反应.

```ts
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/native"; // or "msw/node" or "msw/browser"

let server = setupServer(
  http.get("https://api.example.com/users/1", (req, res, ctx) => {
    return res(ctx.json({ id: 1, name: "John Doe" }));
  })
);

server.listen();

let client = new APIClient("https://api.example.com");
let response = await client.get("/users/1");
let data = await response.json(); // { id: 1, name: "John Doe" }
```

### 处理错误

这个 `APIClient` 类中,除了网络错误外,从不丢出错误。 您可以通过检查响应状态代码处理 API 错误 .

```ts
let client = new APIClient("https://api.example.com");

try {
  let response = await client.get("/users/1");
  if (response.status === 401) {
    // Handle unauthorized error
    throw new Error("Unauthorized");
  }
  // Handle other errors or success
} catch (error) {
  // Handle network error
  console.error(error);
}
```

或者,你可以使用 `after` 用于处理常见API错误的截取器.

```ts
class CustomAPIClient extends APIClient {
  async after(request: Request, response: Response) {
    if (response.status === 401) {
      // Handle unauthorized error
      throw new Error("Unauthorized");
    }

    return response;
  }
}
```

或者你可以使用这个 `on` 用于处理常见的API错误的方法.

```ts
let client = new APIClient("https://api.example.com");

client.interceptors.after.on(async (_, response) => {
  if (response.status === 401) {
    // Handle unauthorized error
    throw new Error("Unauthorized");
  }

  return response;
});
```

### 超时

您可以使用 API 请求设置超时 `signal` 选项.

```ts
let client = new APIClient("https://api.example.com");
await client.get("/users/1", { signal: AbortSignal.timeout(5000) });
```

## 许可证

见 [自由主义](https://npmcn.com/package/%40edgefirst-dev/api-client/LICENSE)

## 作者

-   [塞尔吉奥·沙拉姆布里](https://sergiodxa.com/)

## 常见问题

### @edgefirst-dev/api-client 是什么？

用于提出 API 请求的基本 HTTP 客户端

### 如何安装 @edgefirst-dev/api-client？

在项目目录运行 npm install @edgefirst-dev/api-client，或使用 pnpm add / yarn add / bun add。

### @edgefirst-dev/api-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/edgefirst-dev\_\_api-client 是否存在。

### @edgefirst-dev/api-client 支持 ESM 还是 CommonJS？

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

### @edgefirst-dev/api-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @edgefirst-dev/api-client 可以商用吗？

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

### @edgefirst-dev/api-client 的下载量有多少？

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

### @edgefirst-dev/api-client 还在维护吗？

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