@runapi/requestor

---

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();