sidebarDepth: 2

指南

Requestor

@runapi/requestor: 它提供了一个核心类"Requestor"，通过"Requestor"实例发送 Http 网络请求。

创建请求实例

内置工厂方法创建

目前内置提供了三个工厂方法用于创建"Requestor"实例，分别是：

• 基于浏览器"Fetch API"引擎的"createFetchRequestor"。
• 基于微信小程序"wx.request"引擎的"createWxmpRequestor"。
• 自动适配所在客户端的"createAutoAdaptRequestor"，目前可自动适配浏览器端与微信小程序端。

他们都有两个可选参数。分别是：

1. 全局请求上下文实例，对请求进行全局配置。
2. 第二个为请求环境配置，用于快速切换当前请求环境。

下面以"createFetchRequestor"为例：

import { createRequestContext, createFetchRequestor } from "@runapi/requestor";

const requestContext = createRequestContext()
  .setBaseUrl("https://development.xxx.com")
  .setCredentials(true)
  .setHeaders({ "content-type": "application/json" });

const requestor = createFetchRequestor(requestContext);

自定义工厂方法创建

通过 Requestor 构造函数自定义工厂，但这需要传入一个"Engine"。

下面以"createFetchRequestor"声明为例：

import { FetchEngine, RequestContext, RequestEnv, Requestor } from "@runapi/requestor";

function createFetchRequestor<Environment extends string = any>(requestContext?: RequestContext, requestEnv?: RequestEnv<Environment>) {
  return new Requestor<Response, Environment>(new FetchEngine(), requestContext, requestEnv);
}

发送请求

通过"Requestor"实例的"request"方法可以发送请求。

下面以"createFetchRequestor"发送请求为例：

import { createRequestContext, createFetchRequestor } from "@runapi/requestor";

const requestContext = createRequestContext().setCredentials(true).setHeaders({ "content-type": "application/json" });

const requestEnv = {
  development: "https://development.xxx.com",
  test: "https://test.xxx.com",
};

const requestor = createFetchRequestor(requestContext, requestEnv);

requestor.switch("development");

requestor.request(createRequestContext({ method: "GET", path: "/xxx" }));

Engine

"Engine"是 Http 网络请求引擎。它是发起网络请求时，底层真正的调用引擎对象。RunAPI 可以自由切换底层引擎，以达到跨客户端请求时使用统一的 API 调用风格。"Engine"在创建"Requestor"实例时需要用到。我们可以使用内置提供的两个"Engine"："FetchEngine"和"WxmpEngine"创建"Engine"实例，也可以自己实现"Engine"抽象类自定义请求引擎。

现在我们简单自定义实现一个"Engine"，使用浏览器 Fetch API 作为底层请求对象：

import { Engine, RequestContext } from "@runapi/requestor";

export class FetchEngine extends Engine<Response> {
  doRequest(requestContext: RequestContext) {
    return fetch(requestContext.url, { method: requestContext.method });
  }
}

RequestContext

"RequestContext"是请求上下文对象，它来用携带 Http 请求时配置的相关信息，比如"请求头"，"请求路径"，"请求参数"等。可以通过工厂方法"createRequestContext"创建该实例。在创建"Requestor"实例时传入即为全局配置，在调用"request"发起请求时传入将会与全局配置进行合并，每个配置项都有特定的合并规则。

实例属性：

| 名称 | 作用/描述 | 类型 | 默认值 | 合并规则 | | :---------- | ------------------------ | ---------------------- | --------- | ------------------------- | | baseUrl | 请求基础 URL | string | undefined | 覆盖 | | basePath | 请求基础路径 | string | undefined | 以"/"开头覆盖，反之则拼接 | | path | 请求路径 | string | undefined | 覆盖 | | method | 请求方法 | RequestMethod | "GET" | 覆盖 | | headers | 请求头 | Record<string, string> | undefined | Object.assign | | credentials | 是否允许携带跨域 cookies | RequestCredentials | undefined | 覆盖 | | params | 请求路径参数 | Record<string, any> | undefined | Object.assign | | query | 请求查询参数 | Record<string, any> | undefined | Object.assign | | body | 请求体参数 | Record<string, any> | undefined | Object.assign | | mock | 模拟数据模板 | any | undefined | 覆盖 | | model | 响应结果模型 | Constructor | undefined | 覆盖 | | similar | 类似请求处理方式 | RequestSimilar | undefined | 覆盖 | | others | 需要传递给引擎的其他参数 | any | undefined | 覆盖 | | contextTap | 请求前后回调函数 | ContextTap | undefined | 覆盖 |

实例计算属性：

| 名称 | 作用/描述 | 类型 | | ----------- | -------------------------- | ------ | | fullpath | 请求完整路径 | string | | url | 请求完整 URL | string | | queryString | 查询字符串 | string | | queryUrl | 带查询字符串的请求完整 URL | string |

实例方法：

| 名称 | 作用/描述 | 参数 | | ----- | -------------------- | -------------------- | | send | 发送请求 | "Requestor"实例 | | merge | 合并另一个请求上下文 | "RequestContext"实例 |

以下是用"'requestContext.send'"发送请求:

import { createFetchRequestor, createRequestContext } from "@runapi/requestor";

const requestor = createFetchRequestor(createRequestContext().setBaseUrl("https://development.xxx.com"));

async function getUsers() {
  await createRequestContext({ method: "GET", path: "/users" }).send(requestor);
}

getUsers();

ResponseContext

"ResponseContext"是响应上下文对象，在完成响应时将会返回一个"ResponseContext"实例。

实例属性：

| 名称 | 作用/描述 | | -------------- | ---------------- | | requestContext | 请求上下文 | | response | 请求引擎响应对象 | | status | 响应状态 | | statusText | 响应状态描述 | | result | 响应结果数据 |

异常处理

在发送请求时发生错误时，均会向外抛出"RequestError"类型异常。

以请求失败时，作出友好提示处理为例：

import { createFetchRequestor, createRequestContext, RequestError } from "@runapi/requestor";

const requestor = createFetchRequestor(
  createRequestContext()
    .setBaseUrl("https://development.xxx.com")
    .setContextTap((reqCtx) => (resCtx) => {
      if (!resCtx.ok) throw new Error("Request failed");
    })
);

async function getUsers() {
  try {
    await createRequestContext({ method: "GET", path: "/users" }).send(requestor);
  } catch (error) {
    if (error instanceof RequestError) alert(`${error.status}:${error.message}`);
    // if (error.name === 'RequestError') alert(`${error.status}:${error.message}`);
    console.log(error);
  }
}

getUsers();