发起请求

Mr.Hope大约 6 分钟

发起请求

Oinone 提供统一的网络请求底座，提供了一种便捷的方法来执行 GraphQL 查询（Query）和变更（Mutation）操作，支持批量请求、请求拦截、错误处理等高级功能。

快速上手

import { http } from "@kunlun/dependencies";

// 发起查询（Query）请求
async function getTestQuery() {
  const query = "gql str";
  const result = await http.query("module name", query);
  return result.data[`xx`]["xx"]; // 返回的接口，打印出result对象层次返回
}

// 发起变更（Mutation）请求
async function getTestMutate() {
  const mutation = "gql str";
  const result = await http.mutate("module name", mutation);
  return result.data[`xx`]["xx"]; // 返回的接口，打印出result对象层次返回
}

请求参数

`query` 和 `mutate` 方法

概述

query 和 mutate 方法用于在 GraphQL 中执行查询和变更操作。这两个方法提供了与 GraphQL 服务器交互的接口，允许客户端请求数据或对数据进行修改。

参数

moduleName (string): 请求的模块名称，用于构造请求的 URI。此参数确定了 GraphQL 请求将发送到哪个模块或服务。
body (string | DocumentNode): 包含 GraphQL 查询或变更的语句。这可以是一个字符串形式的 GraphQL 语句，或者是使用 graphql-tag 库构建的 DocumentNode 对象。
variables (ObjectValue, 可选): 一个对象，包含了执行 GraphQL 操作所需的所有变量。每个键值对代表一个变量，其中键为变量名，值为变量的值。
context (RequestContext, 可选): 一个包含特定请求配置的对象。此参数用于提供额外的请求上下文设置，以调整或优化请求行为。
- maxDepth (number, 可选): 定义查询结果的最大嵌套深度，用于防止过深的数据结构可能导致的性能问题。
- batch (boolean, 可选): 指定是否启用批量请求模式。在批量模式下，多个 GraphQL 请求可以合并为一个 HTTP 请求，减少网络延迟和开销。
- __queryParams ({ [key: string]: unknown }, 可选): 一个包含自定义查询参数的对象。这些参数不参与 GraphQL 查询或变更操作，但可能被服务器用于日志记录、权限验证等目的。

返回值

Promise<RawResponse<T>>: 返回一个 Promise 对象，该对象在操作成功完成时解析为 RawResponse<T> 类型，其中 T 表示期望得到的数据类型。RawResponse 对象包含一个 data 字段，该字段封装了根据 body 参数指定的 GraphQL 操作返回的数据。

属性配置

获取 http 实例

import { http } from "@kunlun/dependencies";

API URL 配置

适合生产环境使用 在项目根目录下配置.env 文件

API_BASE_URL=http://127.0.0.1:8090

适合开发环境使用 在 vue.config.js 文件中配置代理
获取/设置 API 接口地址

// 设置API地址
http.setBaseURL("example url");
// 获取API地址
const url = http.getBaseURL(); // example url

请求头配置

// 设置自定义请求头
http.setHeaders({
  Authorization: "Bearer your_token_here",
  "Content-Type": "application/json",
});

// 获取当前配置的请求头
const headers = http.getHeaders();
console.log(headers); // 打印设置的请求头

RSQL 编码配置

// 启用 RSQL 编码
http.setEncodeRsql(true);

// 获取当前 RSQL 编码配置
const isEncodeRsqlEnabled = http.getEncodeRsql(); // 返回 true 或 false

翻译功能配置

// 启用响应结果的翻译
http.setEnableTranslate(true);

// 获取当前翻译功能配置
const isTranslateEnabled = http.getEnableTranslate(); // 返回 true 或 false

使用拦截器

HttpClient 类提供了拦截器的功能，允许您在请求被发送和响应被接收时执行自定义逻辑。这对于处理身份验证、日志记录、错误处理等通用任务非常有用。

设置默认拦截器

HttpClient 类通过 setDefaultMiddleware 方法允许您配置默认的拦截器。这些拦截器将应用于所有的请求和响应。

import { http } from "@kunlun/dependencies";

// 配置默认拦截器
http.setDefaultMiddleware({
  translate: yourTranslateInterceptor, // 翻译拦截器
  networkError: yourNetworkErrorInterceptor, // 网络错误拦截器
  actionRedirect: yourActionRedirectInterceptor, // 动作重定向拦截器
  requestSuccess: yourRequestSuccessInterceptor, // 请求成功拦截器
  loginRedirect: yourLoginRedirectInterceptor, // 登录重定向拦截器
  requestError: yourRequestErrorInterceptor, // 请求错误拦截器
  messageHub: yourMessageHubInterceptor, // 消息中心拦截器
  beforeInterceptors: [yourBeforeInterceptor1, yourBeforeInterceptor2], // 请求前拦截器
  afterInterceptors: [yourAfterInterceptor1, yourAfterInterceptor2], // 请求后拦截器
});

添加自定义拦截器

除了配置默认拦截器外，您还可以通过 setMiddleware 方法添加更多的自定义拦截器。这些拦截器将按照添加的顺序执行。

// 添加自定义拦截器
http.setMiddleware([yourCustomMiddleware1, yourCustomMiddleware2]);

拦截器函数结构

每个拦截器函数接收 operation 和 forward 参数：

operation: 包含即将执行的请求的信息。
forward: 是一个函数，用于将操作传递给链中的下一个拦截器或最终发送请求。

一个拦截器的基本结构如下：

function yourCustomInterceptor(operation, forward) {
  // 在请求被发送前执行的代码
  console.log("Request started:", operation);

  // 调用 forward 函数继续执行下一个拦截器或发送请求
  return forward(operation).map((response) => {
    // 在响应返回后执行的代码
    console.log("Response received:", response);
    // 必须返回响应
    return response;
  });
}

通过使用拦截器，您可以轻松地在请求和响应的生命周期中插入自定义逻辑，从而提高 HttpClient 的灵活性和可扩展性。

内置业务请求方法

以下为 Oinone 提供的业务请求方法及其简单的调用示例。

`queryModuleByName`

// 查询指定名称的模块信息
const moduleInfo = await http.queryModuleByName("ModuleName");

`getModel`

// 获取指定模型的详细信息
const modelInfo = await http.getModel("ModelName");

`getModelByFields`

// 根据指定字段查询模型详细信息
const modelInfo = await http.getModelByFields("ModelName", [
  "field1",
  "field2",
]);

`customQueryPage`

// 执行自定义分页查询
const pageResult = await http.customQueryPage({
  query: "YourGraphQLQuery",
  variables: { page: 1, pageSize: 10 },
  context: {},
});

`queryPage`

// 执行标准分页查询
const pageResult = await http.queryPage({
  model: "ModelName",
  page: 1,
  pageSize: 10,
});

`queryOne`

// 查询单个实体的详细信息
const entity = await http.queryOne({
  model: "ModelName",
  id: "EntityId",
});

`queryOneByWrapper`

// 通过查询条件包装器查询单个实体的详细信息
const entity = await http.queryOneByWrapper("ModelName", "QueryWrapper");

`constructOne`

// 构造一个新的实体实例
const newEntity = await http.constructOne("ModelName");

`constructMirror`

// 构造一个实体的镜像
const entityMirror = await http.constructMirror("ModelName", "EntityId");

`customQuery`

// 执行自定义查询
const customQueryResult = await http.customQuery({
  query: "YourCustomQuery",
  variables: {},
});

`customMutation`

// 执行自定义变更操作
const mutationResult = await http.customMutation({
  mutation: "YourCustomMutation",
  variables: {},
});

`updateOne`

// 更新单个实体的信息
const updateResult = await http.updateOne({
  model: "ModelName",
  id: "EntityId",
  data: {
    /* 更新数据 */
  },
});

`updateBatch`

// 批量更新实体
const batchUpdateResult = await http.updateBatch("ModelName", [
  { id: "EntityId1", data: {} },
  { id: "EntityId2", data: {} },
]);

`insertOne`

// 插入单个新实体
const insertResult = await http.insertOne("ModelName", {
  /* 新实体数据 */
});

`deleteOne`

// 删除单个实体
const deleteResult = await http.deleteOne("ModelName", "EntityId");

`callFunction`

// 调用指定的函数
const functionResult = await http.callFunction("FunctionName", {
  /* 函数参数 */
});

`callFun`

// 调用指定的函数（简写形式）
const funResult = await http.callFun("FunctionName", {
  /* 函数参数 */
});

`requestMutation`

// 执行特定的请求变更操作
const mutationResult = await http.requestMutation("MutationName", {
  /* 变更参数 */
});

`queryReferences`

// 查询实体的引用信息
const references = await http.queryReferences("ModelName", "EntityId");

`loadModules`

// 加载并初始化指定的模块
await http.loadModules(["ModuleName1", "ModuleName2"]);

`queryMaskTemplate`

// 查询模板信息
const maskTemplate = await http.queryMaskTemplate("TemplateId");

`queryPageDslByModelAndName`

// 根据模型和名称查询页面 DSL 信息
const pageDsl = await http.queryPageDslByModelAndName("ModelName", "PageName");

`queryViewDslByModelAndName`

// 根据模型和名称查询视图 DSL 信息
const viewDsl = await http.queryViewDslByModelAndName("ModelName", "ViewName");

`queryViewDslByModelAndTemplate`

// 根据模型和模板查询视图 DSL 信息
const viewDsl = await http.queryViewDslByModelAndTemplate(
  "ModelName",
  "TemplateId"
);

`queryServerActionByModelAndName`

// 根据模型和名称查询服务器端操作信息
const serverAction = await http.queryServerActionByModelAndName(
  "ModelName",
  "ActionName"
);

`queryUrlActionByModelAndName`

// 根据模型和名称查询 URL 动作信息
const urlAction = await http.queryUrlActionByModelAndName(
  "ModelName",
  "ActionName"
);

`queryHomePageDsl`

// 查询首页 DSL 信息
const homePageDsl = await http.queryHomePageDsl();

`customQueryPageWithModule`

// 执行带有模块信息的自定义分页查询
const customPageResult = await http.customQueryPageWithModule("ModuleName", {
  query: "YourCustomPageQuery",
  variables: { page: 1, pageSize: 10 },
});