瓦萨皮..

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

类型脚本对应的 java 时尚 ——同作设计哲学,本土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

安装

npm install @civitas-cerebrum/wasapi

快速启动

1. 用装饰器定义您的 API

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. 构建客户端

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. 执行请求

// 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 参考

装饰者

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

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

@HTTP - 自定义HTTP方法

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

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

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

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> 一个懒惰的要求描述器,它不会执行 直到你调用它的方法之一:

ApiResponse<T>

ResponsePair<R, E>

例外

日志

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

# 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 的比较

重要说明

辩相令事. 含体方法(@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 选项参数中:

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

许可证

麻省理工学院