如何自定义 GraphQL 请求

在开发过程中，有时需要自定义 GraphQL 请求来实现更灵活的数据查询和操作。本文将介绍两种主要的自定义 GraphQL 请求方式：手写 GraphQL 请求和调用平台 API。

方式一：手写 GraphQL 请求

手写 GraphQL 请求是一种直接编写查询或变更语句的方式，适用于更复杂或特定的业务需求。以下分别是 query 和 mutation 请求的示例。

1. 手写 Query 请求

以下是一个自定义 query 请求的示例，用于查询某个资源的语言信息列表。

const customQuery = async () => {
  const query = `{
    resourceLangQuery {
      queryListByEntity(query: {active: ACTIVE, installState: true}) {
        id
        name
        active
        installState
        code
        isoCode
      }
    }
  }`;

  const result = await http.query('resource', query);
  this.list = result.data['resourceLangQuery']['queryListByEntity'];
};

说明：

• query 语句定义了一个请求，查询 resourceLangQuery 下的语言信息。
• 查询的条件是 active 和 installState，只返回符合条件的结果。
• 查询结果包括 id、name、active、installState 等字段。

2. 手写 Mutation 请求

以下是一个 mutation 请求的示例，用于创建新的资源分类信息。

const customMutation = async () => {
  const code = Date.now()
  const name = `测试${code}`

  const mutation = `mutation {
    resourceTaxKindMutation {
      create(data: {code: "${code}", name: "${name}"}) {
        id
        code
        name
        createDate
        writeDate
        createUid
        writeUid
      }
    }
  }`;

  const res = await http.mutate('resource', mutation);
  console.log(res);
};

说明：

• mutation 语句用于创建一个新的资源分类。
• create 操作的参数是一个对象，包含 code 和 name 字段。
• 返回值包括 id、createDate 等字段。

方式二：调用平台的 API

平台 API 提供了简化的 GraphQL 调用方法，可以通过封装的函数来发送 query 和 mutation 请求。这种方式减少了手写 GraphQL 语句的复杂性，更加简洁和易于维护。

1. 调用平台的 Mutation API

使用平台的 customMutation 方法可以简化 Mutation 请求。

declare const customMutation: (
  modelModel: string, 
  method: string | {name: string; argumentName: string}, 
  records: ObjectValue | ListValue, 
  requestFields?: IModelField[] | undefined, 
  responseFields?: IModelField[] | undefined, 
  variables?: ObjectValue | undefined, 
  context?: ObjectValue
) => Promise<any>;

数说明：

• modelModel: 模型编码，定义操作的对象类型。
• method: 变更的方法名或方法对象。
• records: 变更操作的记录对象或记录列表。
• requestFields: 请求字段数组，可选。
• responseFields: 响应字段数组，可选。
• variables: 请求变量，可选。
• context: 上下文信息，可选。

2. 调用平台的 Query API

同样，平台提供了封装的 customQuery 方法，简化了 Query 请求。

declare const customQuery: <T>(
  modelModel: string, 
  method: string, 
  record?: ObjectValue | ListValue | string, 
  requestFields?: IModelField[] | undefined, 
  responseFields?: IModelField[] | undefined, 
  variables?: ObjectValue | undefined, 
  context?: ObjectValue
) => Promise<T>;

参数数说明：

• modelModel: 模型编码，定义查询的对象类型。
• method: 查询的方法名。
• record: 查询条件对象或记录 ID。
• requestFields: 请求字段数组，可选。
• responseFields: 响应字段数组，可选。
• variables: 查询变量，可选。
• context: 上下文信息，可选。

示例：调用平台 API 进行 Mutation 和 Query

// 调用平台的 mutation API
const createTaxKind = async () => {
  const response = await customMutation(
    '模型编码',
    '模型方法',
    { code: '003', name: '测试3' }
  );
  console.log(response);
};

const createTaxKind2 = async () => {
  const response = await customMutation(
    '模型编码',
    {name:  '方法名', argumentName: '参数名'},
    { code: '003', name: '测试3' }
  );
  console.log(response);
};

// 调用平台的 query API
const fetchResourceLanguages = async () => {
  const response = await customQuery(
    '模型编码',
    '模型方法',
    { active: true },
  );
  console.log(response);
};

默认情况下，平台 API 请求只会查询两层，如果要查询第三层，则需要传递context属性

customMutation(
    '模型编码',
    '模型方法',
    { code: '003', name: '测试3' },
    undefined,
    undefined,
    undefined,
    {
      maxDepth: 2
    }
  )

customQuery(
    '模型编码',
    '模型方法',
    { active: true },
    undefined,
    undefined,
    undefined,
    {
      maxDepth: 2
    }
  )

在平台底层maxDepth是从0开始的，0代表了第一层级，所以为2的时候，就是第三层。

对比

• 手写 GraphQL 请求适用于请求参数比较简单的请求
• 调用平台 API 适用于请求参数过于复杂、手动很难写

调用平台 API的弊端

调用平台 API会导致gql的请求体很大，因为底层会把当前模型所有的字段都作为响应体返回。如果请求的层级越深，那么gql请求体越大。

如果想通过手写Graphql的方法拼接复杂的请求参数，可以参考这边文章，里面有详细的讲解。