原始查询和订阅

虽然 @blocklet/server-js 库为大多数常见的 GraphQL 操作提供了便捷的辅助方法，但在某些情况下，您可能需要更大的灵活性或访问 SDK 尚未公开的功能。对于这些高级用例，该库允许您直接执行原始 GraphQL 查询和订阅。

当您需要构建高度特定的查询、在官方封装之前访问最新的 API 功能，或者优化数据获取超出标准方法所能提供的范围时，这种方法是理想的选择。

原始查询

doRawQuery 方法使您能够将任何有效的 GraphQL 查询字符串发送到 Blocklet Server API 端点。这使您可以完全控制所请求的数据及其结构。

query string (required) — 要执行的原始 GraphQL 查询字符串。
requestOptions object — 可选对象，用于高级请求配置，例如自定义标头。

示例

以下是如何使用 doRawQuery 来获取有关已连接节点的基本信息。

doRawQuery Example

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function getNodeVersion() {
  try {
    const query = `{
      getNodeInfo {
        info {
          version
          name
        }
      }
    }`;

    const result = await client.doRawQuery(query);
    console.log('Node Name:', result.getNodeInfo.info.name);
    console.log('Node Version:', result.getNodeInfo.info.version);
  } catch (error) {
    console.error('Failed to execute raw query:', error);
  }
}

getNodeVersion();

响应示例

Response Data

{
  "getNodeInfo": {
    "info": {
      "version": "1.8.22",
      "name": "My Dev Node"
    }
  }
}

此方法返回一个 Promise，该 Promise 会解析为 GraphQL 服务器返回的确切 JSON 数据，从而允许您直接访问嵌套属性。

原始订阅

对于实时数据更新，您可以使用 doRawSubscription 方法建立持久连接并监听服务器推送的事件。与标准查询不同，此方法返回一个订阅对象，允许您注册事件监听器。

query string (required) — 原始 GraphQL 订阅字符串。

示例

此示例演示了如何订阅 Blocklet 状态更改。每当 Blocklet 的状态更新时（例如，从“正在运行”到“已停止”），订阅将推送新数据。

doRawSubscription Example

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function watchBlockletStatus() {
  try {
    const subscriptionQuery = `subscription {
      blockletStatusChanged {
        did
        status
      }
    }`;

    const subscription = await client.doRawSubscription(subscriptionQuery);

    subscription.on('data', (data) => {
      const { did, status } = data.blockletStatusChanged;
      console.log(`Blocklet ${did} status changed to: ${status}`);
    });

    subscription.on('error', (err) => {
      console.error('Subscription error:', err);
    });

    console.log('Listening for blocklet status changes...');
  } catch (error) {
    console.error('Failed to start subscription:', error);
  }
}

watchBlockletStatus();

数据流示例

当 Blocklet 的状态发生变化时，data 事件监听器将收到如下所示的负载：

Streamed Data

{
  "blockletStatusChanged": {
    "did": "z8iZpA6x3M4Jz3J6iK9y6L4oE3nF2aH5c8g7",
    "status": "stopped"
  }
}

当标准辅助方法无法满足您的特定需求时，使用原始查询和订阅提供了一种与 Blocklet Server API 交互的强大方式。要对您的原始查询或任何其他客户端交互进行故障排除，请转到下一节调试。