# @civitas-cerebrum/wasapi 中文文档

规范地址：https://npmcn.com/package/%40civitas-cerebrum/wasapi/

版本：0\.0\.5
npm 元数据更新时间：2026-11-01T09:36:15.778Z
中文译文更新时间：2026-11-09T22:44:59.375Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：73.2 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-04-06T11:30:02.605Z
- 最新版本发布：2026-11-01T09:36:15.464Z
- 近 30 天下载量：2972（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

一个轻量级的REST API客户端库,有流畅的构建器,打入的响应,以及基于装饰器的API定义.

## 安装

```sh
npm install @civitas-cerebrum/wasapi
```

也可以使用：`pnpm add @civitas-cerebrum/wasapi`、`yarn add @civitas-cerebrum/wasapi`、`bun add @civitas-cerebrum/wasapi`

## README

# 瓦萨皮..

[![npm](https://img.shields.io/npm/v/@civitas-cerebrum/wasapi?color=brightgreen&label=wasapi)](https://www.npmjs.com/package/@civitas-cerebrum/wasapi)

**瓦萨皮** 是一个轻量级的TypeScript REST API客户端库,它使用基于装饰器的API定义来简化HTTP服务生成,是一个流畅的构建器,打入的响应,以及智能的投票公用设施.

类型脚本对应的 [java 时尚](https://github.com/Umutayb/wasapi) ——同作设计哲学,本土TypeScript体验.

## 特征

-   **基于装饰器的 API 定义** —— 说 `@GET`, (中文(简体) ), `@POST`, (中文(简体) ), `@PUT`, (中文(简体) ), `@DELETE`, (中文(简体) ), `@PATCH`, (中文(简体) ), `@HTTP`
-   **流利的建设者** ——配置基础 URL,信头,超时,代理,日志
-   **输入的答复** —— 说 `ApiCall<T>`, (中文(简体) ), `ApiResponse<T>`, (中文(简体) ), `ResponsePair<R, E>`
-   **严格/宽大模式** - 投出失败或返回无效
-   **反应投票** —— 说 `monitorResponseCode()`, (中文(简体) ), `monitorFieldValue()`
-   **零 HTTP 依赖性** - 使用本地语言 `fetch` (节点18+)
-   **TC39 第3阶段装饰器** 没有 `experimentalDecorators`,没有 `reflect-metadata`

## 安装

```bash
npm install @civitas-cerebrum/wasapi
```

## 快速启动

### 1\. 用装饰器定义您的 API

```typescript
import { GET, POST, DELETE, ApiCall } from '@civitas-cerebrum/wasapi';

interface User {
  id: string;
  name: string;
  email: string;
}

class UserApi {
  @GET('/users')
  getUsers(): ApiCall<User[]> { return null!; }

  @GET('/users/:id')
  getUser(pathParams: { id: string }): ApiCall<User> { return null!; }

  @POST('/users')
  createUser(body: { name: string; email: string }): ApiCall<User> { return null!; }

  @DELETE('/users/:id')
  deleteUser(pathParams: { id: string }): ApiCall<void> { return null!; }
}
```

### 2\. 构建客户端

```typescript
import { WasapiClient } from '@civitas-cerebrum/wasapi';

const api = new WasapiClient.Builder()
  .setBaseUrl('https://api.example.com')
  .setHeaders({ Authorization: 'Bearer token' })
  .setLogHeaders(true)
  .build(UserApi);
```

### 3\. 执行请求

```typescript
// Lenient mode (default) — returns null on failure
const users = await api.getUsers().perform();

// Strict mode — throws FailedCallException on non-2xx
const users = await api.getUsers().perform(true);

// Strict + log response body
const users = await api.getUsers().perform(true, true);

// Full response wrapper
const response = await api.getUser({ id: '5' }).getResponse();
console.log(response.status);    // 200
console.log(response.body);      // User object
console.log(response.headers);   // Record<string, string>

// Typed error handling
const pair = await api.getUser({ id: 'bad' }).getResponsePair(ErrorModel);
if (pair.isError()) {
  console.log(pair.errorBody);   // ErrorModel instance
}
```

## API 参考

### 装饰者

| 装饰 | 说明 | 方法参数 |
| --- | --- | --- |
| `@GET(path)` | HTTP 获取 | `(pathParams?, queryParams?, options?)` |
| `@POST(path)` | HTTP 邮编 | `(body?, pathParams?, queryParams?, options?)` |
| `@PUT(path)` | HTTP PUT 软件 | `(body?, pathParams?, queryParams?, options?)` |
| `@PATCH(path)` | 哈特普・帕奇 | `(body?, pathParams?, queryParams?, options?)` |
| `@DELETE(path)` | HTTP 抖音 | `(pathParams?, queryParams?, options?)` |
| `@HTTP(method, path, hasBody?)` | 自定义方法 | 基于 `hasBody` |

**路径参数** 使用情况 `:param` 语法——例如, `/users/:id` 替换为 `pathParams: { id: '5' }`。 。 。 .

**查询参数** 后附为 `?key=value` 从 `queryParams: Record<string, string>`。 。 。 .

### `@HTTP` - 自定义HTTP方法

对于非常规方法,如 `PURGE`, (中文(简体) ), `COPY`,或 `LOCK`数字 :

```typescript
import { HTTP, ApiCall } from '@civitas-cerebrum/wasapi';

class CacheApi {
  @HTTP('PURGE', '/cache/:key')
  purge(pathParams: { key: string }): ApiCall<void> { return null!; }

  @HTTP('REPORT', '/analytics', true)  // hasBody = true
  report(body: ReportRequest): ApiCall<ReportResult> { return null!; }
}
```

### `WasapiClient.Builder`

| 方法 | 说明 | 默认 |
| --- | --- | --- |
| `setBaseUrl(url)` | 所有请求的基准 URL | _所需经费_ |
| `setHeaders(headers)` | 默认信头( 按请求合并) | `{}` |
| `setTimeout(seconds)` | 请求超时( 秒) | `60` |
| `setLogHeaders(bool)` | 日志请求信头 | `true` |
| `setLogRequestBody(bool)` | 日志请求正文 | `false` |
| `setDetailedLogging(bool)` | 日志响应机构 | `false` |
| `setFollowRedirects(bool)` | 跟随 HTTP 重定向 | `false` |
| `build(ApiClass)` | 构建已键入的 API 代理 | —— 说 |

传出 a `ContextStore` 实例到构建器从配置中读取默认值 :

```typescript
const store = new ContextStore();
store.put('wasapi.baseUrl', 'https://api.example.com');
store.put('wasapi.timeout', 30);

const api = new WasapiClient.Builder(store).build(MyApi);
```

### `ApiCall<T>`

每个装饰方法返回一个 `ApiCall<T>` 一个懒惰的要求描述器,它不会执行 直到你调用它的方法之一:

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `perform(strict?, printBody?, ...errorModels)` | `Promise<T | null>` | 执行并还身. 严格投出失败. |
| `getResponse(strict?, printBody?)` | `Promise<ApiResponse<T>>` | 完全反应包装 状态,标题,身体. |
| `getResponsePair(ErrorClass)` | `Promise<ResponsePair<ApiResponse<T>, E>>` | 反应+打出错误正文. |
| `monitorResponseCode(code, timeout, interval?)` | `Promise<ApiResponse<T>>` | 在 HTTP 状态匹配前进行投票 . |
| `monitorFieldValue(field, value, timeout, interval?)` | `Promise<T>` | 直到反应体场对齐为止. |
| `clone()` | `ApiCall<T>` | 独立副本,供重试/抽取. |

### `ApiResponse<T>`

| 财产/方法 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `number` | HTTP 状态代码 |
| `statusText` | `string` | HTTP 状态文本 |
| `headers` | `Record<string, string>` | 答复信头 |
| `ok` | `boolean` | 若状态为 True, 200 - 299 |
| `body` | `T | null` | 解析过的JSON体 |
| `rawBody` | `string` | 原始响应文本 |
| `isSuccessful()` | `boolean` | 与 `ok` |
| `errorBody(ErrorClass?)` | `E | null` | 淡化错误正文 |

### `ResponsePair<R, E>`

| 财产/方法 | 类型 | 说明 |
| --- | --- | --- |
| `response` | `R` | API的回应 |
| `errorBody` | `E | null` | 已键入出错正文( 成功时未显示) |
| `isError()` | `boolean` | 如果错误Body不是无效, 则为真 |

### 例外

| 类 | 说明 |
| --- | --- |
| `FailedCallException` | 在非-2xx上投入了严格模式. 有过 `statusCode`, (中文(简体) ), `responseBody`, (中文(简体) ), `url`。 。 。 . |
| `WasapiException` | 一般库出错( 超时出错, 缺少配置等) |

## 日志

使用 `debug` 软件包 `wasapi:*` 名称空间。 默认启用 .

```bash
# Suppress all wasapi logs
WASAPI_DEBUG=false npx tsx tests/my-test.ts

# Show only request logs
DEBUG=wasapi:request npx tsx tests/my-test.ts
```

## 与 Java Wasapi 的比较

| 爪哇语 (Retrofit) | 类型脚本( 此软件包) |
| --- | --- |
| `@GET` 编号 : `@POST` 关于接口的说明 | `@GET` 编号 : `@POST` 关于类方法的装饰器 |
| `retrofit.create(Service.class)` | `builder.build(ServiceClass)` ——返回代理服务器 |
| `Call<T>` | `ApiCall<T>` |
| `Response<T>` | `ApiResponse<T>` |
| `ResponsePair<R, E>` | `ResponsePair<R, E>` |
| `Caller.perform(call, strict, printBody)` | `apiCall.perform(strict, printBody)` |
| `WasapiUtilities.monitorResponseCode()` | `apiCall.monitorResponseCode()` |
| 扩展 `WasapiUtilities` | 不需要继承 `ApiCall<T>` |

## 重要说明

**辩相令事.** 含体方法(`@POST`, (中文(简体) ), `@PUT`, (中文(简体) ), `@PATCH`采取 `(body, pathParams?, queryParams?, options?)`. 非机构方法`@GET`, (中文(简体) ), `@DELETE`采取 `(pathParams?, queryParams?, options?)`。TypeScript在编译时执行,但在动态构建调用时要小心.

**`perform()` 返回时 `null` 宽大模式** 对于空成功响应(如204)和失败请求。 如果您需要区分这些案件,请使用 `getResponse()` 使你饱满 `ApiResponse<T>` 有状态代码.

**反应体是普通的 JSON 对象**而不是一个阶级的例子. `ApiCall<User>.perform()` 返回形状为 `User`,没有实例 `User` 还有方法 这是标准的 TypeScript REST 客户端行为(与 arxios, ky等相同).

**超时单位 :** 构建器 `setTimeout()` 进入 **秒数**投票方法`monitorResponseCode`, (中文(简体) ), `monitorFieldValue`采取 **毫秒** 暂停和间隔.

**通过选项格式数据 :** 要通过装饰器路径发送多段请求, 请通过 `formData` 选项参数中:

```typescript
const form = WasapiClient.getMultipartFromFile('./photo.jpg', 'avatar');
await api.uploadAvatar(undefined, undefined, { formData: form }).perform(true);
```

## 许可证

麻省理工学院

## 常见问题

### @civitas-cerebrum/wasapi 是什么？

一个轻量级的REST API客户端库,有流畅的构建器,打入的响应,以及基于装饰器的API定义\.

### 如何安装 @civitas-cerebrum/wasapi？

在项目目录运行 npm install @civitas-cerebrum/wasapi，或使用 pnpm add / yarn add / bun add。

### @civitas-cerebrum/wasapi 支持 TypeScript 吗？

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

### @civitas-cerebrum/wasapi 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @civitas-cerebrum/wasapi 可以商用吗？

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

### @civitas-cerebrum/wasapi 的下载量有多少？

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

### @civitas-cerebrum/wasapi 还在维护吗？

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