Sui API：如何为您的 dApp 选择合适的接口

Sui 的 API 格局正在发生变化。多年来，开发者通过 JSON-RPC 与网络交互，但 Sui 基金会已宣布弃用时间表，使 gRPC 和 GraphQL 成为推荐的未来路径。如果您正在搜索“sui api”，您可能正在试图弄清楚该使用哪种接口、如何连接，以及如何处理 JSON-RPC 的日落。

本指南将为您理清思路。您将了解 Sui API 接口之间的差异，获得实用的代码示例，并了解如何为您的项目选择合适的接口。我们还将展示 OnFinality 托管的 Sui 基础设施如何简化您的访问。

决策指南：您应该使用哪种 Sui API？

在深入细节之前，这里有一个快速框架，可帮助您决定哪种 Sui API 接口适合您的需求：

如果您正在启动新项目，请选择 GraphQL 或 gRPC。 JSON-RPC 已弃用，并将在 2026 年 7 月下旬在 Sui 基金会主网全节点上禁用。基于已弃用的接口构建意味着您很快需要迁移。

如果您有现有的 JSON-RPC 集成，请立即规划迁移。 时间表很明确：JSON-RPC 将在 2026 年 7 月 27 日那一周在 Sui 基金会主网全节点上禁用，并在 2026 年 10 月中旬完全移除代码。立即开始评估 gRPC 或 GraphQL。

如果您需要托管解决方案，请考虑 OnFinality。 OnFinality 为 Sui 主网和测试网提供可靠的 Sui RPC 端点，处理基础设施，以便您可以专注于构建。查看我们的 Sui 网络页面 了解详情。

了解 Sui 的 API 接口

Sui 提供三种主要的 API 接口，每种都有其优势：

JSON-RPC（已弃用）

JSON-RPC 一直是与 Sui 交互的标准。它是一种基于 HTTP 的简单协议，使用 JSON 进行请求和响应。大多数现有的 Sui 工具和 SDK 使用 JSON-RPC。

JSON-RPC 请求示例：

curl -X POST https://rpc.sui.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getAllBalances",
    "params": ["0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961"]
  }'

为什么弃用： Sui 基金会正在转向更高效、可扩展的协议。JSON-RPC 在流式传输和性能方面的局限性导致了这一决定。

gRPC

gRPC 是一个高性能、开源的 RPC 框架，使用 Protocol Buffers 进行序列化。它支持双向流式传输，非常适合实时数据和高吞吐量应用。

gRPC 客户端示例（Node.js）：

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('sui.proto');
const suiProto = grpc.loadPackageDefinition(packageDefinition);

const client = new suiProto.sui.NodeService('https://rpc.sui.io', grpc.credentials.createSsl());

client.getLatestCheckpointSequenceNumber({}, (err, response) => {
  if (err) {
    console.error(err);
  } else {
    console.log('Latest checkpoint:', response);
  }
});

为什么选择 gRPC： 它专为性能而设计，具有比 JSON-RPC 更低的延迟和更高的吞吐量。它也是强类型的，减少了错误。

GraphQL

GraphQL 是一种查询语言，允许客户端精确请求所需的数据。它非常适合前端应用，您希望最小化数据传输并简化客户端逻辑。

GraphQL 查询示例：

query {
  address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
    balance
    coins {
      nodes {
        coinType
        balance
      }
    }
  }
}

为什么选择 GraphQL： 它提供了一种灵活高效的方式来查询链上数据。您可以在单个请求中获取多个资源，减少网络开销。

通过 OnFinality 连接到 Sui

OnFinality 为 Sui 主网和测试网提供托管的 Sui RPC 端点。这意味着您不必运行自己的全节点，并且可以获得可靠、可扩展的网络访问。

Sui 主网 RPC 端点：

https://rpc.sui.io

Sui 测试网 RPC 端点：

https://rpc.testnet.sui.io

这些端点支持 HTTP 和 WebSocket 传输。对于生产应用，您需要使用具有更高速率限制的专用端点。查看我们的 定价页面 了解详情。

代码示例：发起您的第一个 Sui API 调用

让我们通过一个简单的示例，使用 JavaScript 获取 Sui 地址的余额。

使用 JSON-RPC（临时）

const axios = require('axios');

const url = 'https://rpc.sui.io';
const address = '0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961';

const payload = {
  jsonrpc: '2.0',
  id: 1,
  method: 'suix_getAllBalances',
  params: [address]
};

axios.post(url, payload)
  .then(response => {
    console.log(response.data.result);
  })
  .catch(error => {
    console.error(error);
  });

使用 GraphQL（推荐）

const axios = require('axios');

const url = 'https://rpc.sui.io/graphql';
const query = `
  query {
    address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
      balance
    }
  }
`;

axios.post(url, { query })
  .then(response => {
    console.log(response.data.data);
  })
  .catch(error => {
    console.error(error);
  });

常见陷阱及如何避免

1. 在新项目中使用已弃用的 JSON-RPC。 避免这种情况。从 GraphQL 或 gRPC 开始，以免日后迁移。
2. 不处理速率限制。 公共端点有速率限制。对于生产环境，请使用像 OnFinality 这样的托管提供商，以获得更高的限制和专用资源。
3. 忽略 WebSocket 支持。 对于实时更新（例如交易通知），请使用 WebSocket。OnFinality 在其端点上支持 WebSocket。
4. 忘记测试网。 始终先在测试网上测试您的集成。OnFinality 为此提供了 Sui 测试网端点。

从 JSON-RPC 迁移到 gRPC 或 GraphQL 的路径

如果您有现有的 JSON-RPC 集成，这里有一个分步计划：

1. 审计您当前的使用情况。 确定您使用的 JSON-RPC 方法，并将它们映射到 gRPC 或 GraphQL 的等效方法。
2. 选择您的目标接口。 对于后端服务，gRPC 通常是最佳选择。对于前端，GraphQL 更灵活。
3. 设置测试环境。 使用 Sui 测试网来试验新接口。
4. 重构您的代码。 更新您的 SDK 和库。Sui SDK 正在更新以支持 gRPC 和 GraphQL。
5. 彻底测试。 确保所有功能按预期工作。
6. 部署并监控。 逐步推出迁移，并监控错误。

关键要点

• Sui 提供三种 API 接口：JSON-RPC（已弃用）、gRPC 和 GraphQL。
• JSON-RPC 将在 2026 年 7 月下旬禁用，因此请立即规划迁移。
• 为后端服务选择 gRPC，为前端应用选择 GraphQL。
• OnFinality 为 Sui 主网和测试网提供托管的 Sui RPC 端点，简化您的基础设施。
• 在部署到主网之前，始终在测试网上进行测试。

常见问题解答

什么是 Sui API？

Sui API 是指允许开发者与 Sui 区块链交互的一组接口。它包括 JSON-RPC、gRPC 和 GraphQL。

JSON-RPC 在 Sui 上是否已弃用？

是的，Sui 基金会已宣布 JSON-RPC 将在 2026 年 7 月下旬在主网全节点上弃用并禁用。

我应该使用哪种 Sui API？

对于新项目，前端使用 GraphQL，后端服务使用 gRPC。JSON-RPC 仅适用于临时或遗留集成。

OnFinality 是否支持 Sui？

是的，OnFinality 为 Sui 主网和测试网提供托管的 Sui RPC 端点。访问我们的 Sui 网络页面 了解更多信息。

如何获取 Sui API 密钥？

使用 OnFinality，您可以注册并为 Sui 端点获取 API 密钥。查看我们的 定价页面 了解详情。

Sui API 的速率限制是多少？

速率限制因提供商和计划而异。OnFinality 提供具有不同速率限制的灵活计划。请联系我们了解具体详情。

我可以将 WebSocket 与 Sui API 一起使用吗？

是的，Sui 支持 WebSocket 用于实时数据。OnFinality 端点支持 WebSocket 连接。

如何从 JSON-RPC 迁移到 gRPC？

按照上面概述的迁移路径进行操作。Sui 基金会提供了 JSON-RPC 迁移指南，其中包含详细步骤。

什么是 SuiJSON？

SuiJSON 是一种基于 JSON 的格式，将 JSON 输入与 Move 调用参数对齐。它具有特定的类型强制规则，以确保与 Move 类型的兼容性。

在哪里可以找到 Sui API 参考？

官方 Sui API 参考 提供了 JSON-RPC 方法的完整文档。对于 gRPC 和 GraphQL，请参阅 Sui 文档。