如何使用 RPC 和数据提供者访问 Sui 数据？

Sui 是一个高吞吐量网络，应用状态存在于对象中，而不是单一的全局账户账本。这种设计决定了您读取数据的方式：大多数查询以对象为中心，RPC 接口围绕对象、交易、检查点和事件构建。如果您正在将钱包、索引器或仪表板连接到 Sui，您需要一个能够在实际流量下可靠回答这些查询的端点。

本页面是 Sui RPC 和数据访问的实用参考。它解释了 RPC 接口暴露的内容、如何配置端点、如何发出真实请求，以及如何在公共全节点、托管 RPC API 和专用节点之间做出选择。

选择您的 Sui 数据访问路径

在编写集成代码之前，请确定哪种访问路径与您的工作负载匹配。三种常见路径的主要区别在于隔离性、容量以及您需要承担多少运维工作。

一个快速的经验法则：如果您仍在探索 API，公共全节点就足够了。一旦有了真实用户，就转向托管 RPC API，这样您就不会争抢共享容量。如果您的工作负载很大、突发性强或需要可预测的行为，请考虑专用节点，这样您的流量就不会受到其他租户的影响。

OnFinality 通过其 API 服务 和专用节点选项提供 Sui RPC，因此您可以从托管端点开始，并随着负载增长迁移到专用基础设施。您可以在 Sui RPC 页面 上查看网络详情。

Sui RPC 接口暴露的内容

Sui 全节点 JSON-RPC API 围绕网络的核心数据类型组织。您最常使用的方法分为以下几组：

• 对象读取：按 ID 获取对象，包括其类型、所有者和版本。
• 交易读取：按摘要获取交易并检查其效果和事件。
• 检查点读取：检索检查点数据及其包含的交易。
• 事件查询：按类型、发送者或模块查询事件，这是大多数索引器跟踪活动的方式。
• 代币和余额读取：查找地址的代币对象和余额。
• 执行：提交已签名交易以执行。

由于 Sui 状态基于对象，您通常会将地址解析为其拥有的对象，然后读取每个对象，而不是读取单个账户余额。请尽早围绕这种模式规划您的数据模型，因为它会影响您如何缓存和索引。

方法名称和参数会随网络发展而变化，因此请将官方 Sui 文档视为确切方法列表和请求格式的权威来源。本页面重点介绍如何连接和操作该接口。

配置 Sui 端点

Sui 端点是一个 HTTP JSON-RPC URL。您将客户端指向它并发送标准 JSON-RPC 请求。相同的 URL 适用于 curl、JavaScript SDK 和后端服务。

将端点存储在环境变量中，而不是硬编码，这样您就可以在开发和生产之间切换而无需更改代码：

# .env
export SUI_RPC_URL="https://your-onfinality-sui-endpoint"

然后从您的客户端引用它。在 JavaScript 中，Sui SDK 在创建客户端时接受全节点 URL：

import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';

// 在生产中使用您的托管端点；该辅助函数便于本地测试。
const client = new SuiClient({
  url: process.env.SUI_RPC_URL ?? getFullnodeUrl('mainnet'),
});

const object = await client.getObject({
  id: '0xYOUR_OBJECT_ID',
  options: { showType: true, showOwner: true },
});

console.log(object.data?.type, object.data?.owner);

要原始检查您的端点是否可达并返回数据，请直接发送 JSON-RPC 请求：

curl -s "$SUI_RPC_URL" \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sui_getLatestCheckpointSequenceNumber",
    "params": []
  }'

健康的响应会返回一个包含最新检查点序列号的 JSON 结果。如果您得到的是错误对象，请先检查方法名称和参数，然后检查端点本身。

读取 Sui 数据：对象、交易和事件

大多数 Sui 集成遵循相同的三步模式：解析您需要的内容，读取它，然后跟踪变化。

1. 解析。给定地址或已知 ID，找到您关心的对象或交易。对于地址，查询拥有的对象。对于已知摘要，直接获取交易。
2. 读取。获取您需要的字段的对象或交易。只请求您使用的选项，因为大型响应会消耗带宽和时间。
3. 跟踪。订阅或轮询事件和检查点，以便您的应用状态保持最新。

事件查询是大多数索引器的支柱。您按事件类型、模块或发送者进行过滤，然后分页浏览结果。由于繁忙网络上的事件量可能很高，请设计查询以分页而不是一次性请求所有内容，并存储游标以便在重启后恢复。

如果您正在构建需要历史状态的后端，请确认您的提供商为您需要的范围提供归档访问。并非每个端点都保留完整历史，这种差距是项目后期常见的意外来源。

生产就绪检查清单

在将真实流量发送到 Sui 端点之前，请使用此检查清单。它的编写方式使您可以将其交给负责应用可靠性的人员。

如果您无法回答其中几项，托管 RPC API 通常比运行自己的全节点更快。OnFinality 的 RPC 定价 页面列出了计划层级，支持的 RPC 网络 列表显示了 Sui 与其他链的并列位置。

常见故障模式及如何调试

Sui RPC 问题通常分为几个可识别的类别。在更改任何内容之前，将症状与可能的原因匹配。

一个有用的调试习惯是并排比较两个端点。从每个端点查询最新的检查点序列号并进行比较。如果其中一个持续落后，则该端点滞后，您应该将流量从它转移，直到它赶上。

有关端点选择和故障转移设计的更广泛介绍，请参阅 如何选择 RPC 提供商。

何时迁移到专用 Sui 节点

托管 RPC 可以很好地处理大多数生产工作负载。当以下一种或多种情况适用时，专用节点值得考虑：

• 您的流量足够大，共享容量导致不可预测的延迟。
• 出于合规、安全或数据驻留原因，您需要隔离。
• 您运行大量事件索引或归档查询，在共享层级上成本高昂。
• 您希望控制节点版本和配置，而无需自己操作硬件。

专用节点并不自动是正确答案。它增加了成本和规划，只有当您的工作负载足够稳定以证明其合理性时才有回报。如果您不确定，请从托管开始并测量。当延迟或限流成为反复出现的问题时，这就是您评估专用基础设施的信号。OnFinality 的 专用节点 产品是查看该选项的地方。

关键要点

• Sui 数据访问以对象为中心，因此请围绕对象、交易、检查点和事件设计查询和缓存。
• 公共全节点适合学习；生产应用应使用托管 RPC API，高流量或隔离的工作负载应考虑专用节点。
• 将端点保留在配置中，定义故障转移，并在启动前设置超时和重试。
• 事件查询需要过滤器和游标；归档需求必须提前确认。
• 大多数 Sui RPC 问题可以通过比较检查点序列号并根据当前文档检查方法名称来诊断。

常见问题

我需要 Sui 全节点来读取数据吗？

不需要。您可以通过任何可访问的 JSON-RPC 端点读取 Sui 数据，包括托管 RPC API。只有当您需要对节点的完全控制或特定的隔离要求时，才需要运行自己的全节点。

Sui RPC 提供商和数据提供商有什么区别？

RPC 提供商为您提供一个实时端点，针对当前链状态回答 JSON-RPC 查询。数据提供商可能在此基础上添加索引、历史查询或聚合数据集。许多团队同时使用两者：RPC 用于实时读写，索引数据用于分析和历史。

为什么我的 Sui 事件查询会超时？

没有过滤器或分页的宽泛事件查询可能会返回非常大的结果集。按类型、模块或发送者添加过滤器，并使用游标分页浏览结果，以便每个请求保持较小。

如何检查 Sui 端点是否健康？

从端点查询最新的检查点序列号，并与第二个端点进行比较。持续较低的数字意味着端点滞后。

我可以使用 OnFinality 进行 Sui RPC 吗？

可以。OnFinality 通过其 API 服务和专用节点选项提供 Sui RPC。请参阅 Sui RPC 页面 了解网络详情，以及 RPC 定价 了解计划信息。