Sui gRPC API：类型化 Sui 接口实用指南

gRPC 在 Sui 数据访问策略中的角色

Sui 正在逐步将其主要 SDK 和数据访问路径从旧版 JSON-RPC 转向带有生成的类型化客户端的 gRPC API。这一转变反映了行业向模式驱动接口发展的更广泛趋势，可减少集成错误并提升性能。对于新集成而言，理解 gRPC 接口正变得至关重要，尽管 JSON-RPC 和 GraphQL 仍可用于特定用例。

Sui API 参考文档记录了三种不同的数据访问接口：JSON-RPC、gRPC 和 GraphQL。每种接口服务于不同需求。JSON-RPC 提供广泛的兼容性和简单的请求-响应模型。GraphQL 在索引器之上提供查询语言，允许客户端指定响应的确切结构。gRPC 提供强类型、高性能的二进制协议，并支持流式传输。Sui 开发者文档提供了 SDK 和数据访问指南，帮助开发者为其应用选择合适的接口。

本文重点介绍 gRPC API：它是什么、在协议层面如何工作，以及如何使用 Sui TypeScript SDK 调用它。文章还将 gRPC 与 JSON-RPC 和 GraphQL 进行对比，以便您就使用哪种接口做出明智决策。有关 Sui 网络访问的更广泛概述，请参阅 Sui 网络页面和 OnFinality Learn 中心。

• gRPC 是一个现代的、基于 HTTP/2 的 RPC 框架，使用 Protobuf 进行消息序列化。
• Sui 的 gRPC API 提供从 .proto 服务定义生成的类型化客户端。
• 它支持一元和流式调用，实现高效的数据检索和实时更新。
• 该 API 正在演进；请始终固定您的 SDK 版本并检查提供商支持。

gRPC 协议基础：HTTP/2、Protobuf 与流式传输

gRPC 是一个开源 RPC 框架，使用 HTTP/2 作为传输层，使用 Protocol Buffers（Protobuf）作为接口定义语言和消息格式。正如 gRPC 简介所述，gRPC 使客户端和服务器应用能够透明通信，并简化了连接系统的构建。它支持四种服务方法类型：一元、服务器流式、客户端流式和双向流式。

在 gRPC 调用中，客户端调用服务存根上的方法，传入类型化请求消息。存根将消息序列化为 Protobuf 二进制格式，并通过 HTTP/2 流发送。服务器反序列化请求、处理请求并返回类型化响应消息。由于服务契约定义在 .proto 文件中，客户端和服务器共享同一模式，从而实现代码生成和编译时类型检查。

这与 JSON-RPC 形成对比，后者客户端发送包含方法名和参数的 JSON 对象，服务器返回 JSON 对象。没有正式模式，因此类型错误只能在运行时捕获。gRPC 的二进制编码也比 JSON 文本更紧凑，可以减少带宽并提升性能，尤其对于大负载或高频调用。

• HTTP/2 多路复用允许在单个连接上进行多个并发调用。
• Protobuf 提供高效的二进制序列化和强类型。
• 流式传输支持实时数据流，例如交易订阅。
• 生成的客户端存根减少样板代码并强制执行服务契约。

Sui gRPC 与 JSON-RPC 和 GraphQL 的对比

Sui 的 JSON-RPC API 是一种传统的远程过程调用接口，每个请求指定方法名和 JSON 负载。它被广泛支持，且易于从任何 HTTP 客户端使用，但缺乏正式模式，因此开发者必须查阅文档以了解预期参数和响应结构。Sui RPC 指南（RPC Assistant）详细介绍了 JSON-RPC 的使用。JSON-RPC 方法也可能被弃用，如 Sui JSON-RPC 方法弃用文章所述。

相比之下，Sui GraphQL 是在索引器之上的查询语言。客户端指定所需的确切字段，服务器仅返回该数据。这种灵活性对于复杂查询和历史聚合非常强大，但它需要索引器，可能不适合实时交易提交。Sui GraphQL API 查询接口文章深入探讨了这一接口。

gRPC 介于这两个极端之间。它像 GraphQL 一样提供类型化、模式驱动的接口，但具有二进制协议的性能和流式能力。与 GraphQL 不同，gRPC 不是查询语言；您使用类型化请求调用预定义方法。与 JSON-RPC 不同，gRPC 需要代码生成和支持 HTTP/2 的环境。对于需要类型安全和效率的新集成，gRPC 正日益成为首选。

• JSON-RPC：方法 + JSON 文本，无模式，广泛兼容。
• GraphQL：在索引器之上的查询语言，客户端指定响应结构。
• gRPC：类型化客户端，Protobuf 二进制编码，流式传输，需要 HTTP/2。
• 每种接口都有权衡；根据应用需求选择。

协议层面 Sui gRPC 调用的剖析

在协议层面，Sui gRPC 调用始于客户端存根调用服务方法，例如 GetTransaction 或 GetObject。客户端构造类型化请求消息，例如包含交易摘要的 GetTransactionRequest。存根将此消息序列化为 Protobuf 二进制，并通过 HTTP/2 流发送到服务器。服务器处理请求并返回类型化响应消息，例如 GetTransactionResponse，客户端将其反序列化为原生对象。

这与 JSON-RPC 调用有根本不同，后者客户端发送带有 JSON 正文的 HTTP POST，例如 {"jsonrpc":"2.0","method":"sui_getTransactionBlock","params":["0x..."],"id":1}。JSON-RPC 服务器解析 JSON、执行方法并返回 JSON 响应。没有编译时契约；客户端必须从文档中了解方法名和参数顺序。

gRPC 服务定义包含在 .proto 文件中，Sui SDK 将其包装并暴露为类型化客户端。这意味着您可以在 IDE 中使用自动补全和类型检查，降低运行时错误的风险。SDK 还处理连接管理、序列化和反序列化，因此您可以专注于应用逻辑。

// Example .proto snippet (simplified)
service SuiGrpcService {
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);
  rpc GetObject(GetObjectRequest) returns (GetObjectResponse);
}

message GetTransactionRequest {
  string digest = 1;
}

message GetTransactionResponse {
  Transaction transaction = 1;
}

为 gRPC 设置 Sui TypeScript SDK

要从 Node.js 或 TypeScript 调用 Sui gRPC API，您需要 Sui TypeScript SDK，其中包含 gRPC 客户端。该 SDK 可在 npm 上获取，并可通过包管理器安装。开始之前，请确保您的环境支持 HTTP/2，因为 gRPC 需要它。Node.js 内置 HTTP/2 支持，因此开箱即用。

您还需要一个 Sui gRPC 端点。像 OnFinality 这样的提供商提供 Sui RPC 端点；请查看 API 服务页面了解可用接口。务必确认您的提供商支持 gRPC，因为并非所有 RPC 端点都暴露它。RPC 定价页面可帮助您选择包含 gRPC 访问的计划。

安装后，您可以导入 gRPC 客户端并创建连接。SDK 通常提供 SuiGrpcClient 类或类似类，您可以使用端点 URL 实例化它。如果您的提供商需要 API 密钥，您可能还需要配置身份验证。请参阅 SDK 文档以了解确切的类名和配置选项，因为它们可能因版本而异。

// Install the Sui TypeScript SDK
npm install @mysten/sui

// Import the gRPC client (class name may vary by SDK version)
import { SuiGrpcClient } from '@mysten/sui/grpc';

// Create a client instance
const client = new SuiGrpcClient({
  url: 'https://sui-grpc.example.com', // replace with your provider's gRPC endpoint
  // apiKey: 'your-api-key', // if required
});

可运行示例：使用类型化 gRPC 客户端查询交易

以下 Node.js/TypeScript 示例演示如何连接到 Sui gRPC 端点，并使用类型化客户端通过交易摘要检索交易。然后展示使用 JSON-RPC 的等效操作以进行对比。此示例假设您已安装 Sui TypeScript SDK 并拥有 gRPC 端点 URL。

将占位符端点和交易摘要替换为您自己的值。示例使用 async/await 以提高可读性。请注意，确切的方法名和响应结构可能因 SDK 版本而略有不同；请始终查阅 SDK 的文档或类型定义。

运行示例后，您应该会看到交易详情打印到控制台。gRPC 响应是类型化对象，而 JSON-RPC 响应是普通 JSON 对象。这说明了开发者体验的差异：使用 gRPC 时，您的 IDE 可以为响应字段提供自动补全和类型检查。

import { SuiGrpcClient } from '@mysten/sui/grpc';
import fetch from 'node-fetch'; // for JSON-RPC comparison

const GRPC_URL = 'https://sui-grpc.example.com';
const JSON_RPC_URL = 'https://sui-json-rpc.example.com';
const TX_DIGEST = '0x...'; // replace with a real transaction digest

async function queryWithGrpc() {
  const client = new SuiGrpcClient({ url: GRPC_URL });
  const response = await client.getTransaction({ digest: TX_DIGEST });
  console.log('gRPC response:', response);
  // response is a typed object, e.g., response.transaction
}

async function queryWithJsonRpc() {
  const body = {
    jsonrpc: '2.0',
    method: 'sui_getTransactionBlock',
    params: [TX_DIGEST, { showInput: true, showEffects: true }],
    id: 1,
  };
  const res = await fetch(JSON_RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  console.log('JSON-RPC response:', json);
}

(async () => {
  await queryWithGrpc();
  await queryWithJsonRpc();
})();

可复现的测量：对比 gRPC 和 JSON-RPC 调用

为了评估 gRPC 和 JSON-RPC 在您的用例中的实际差异，您可以使用自己的端点进行可复现的测量。下表提供了记录关键指标的模板。通过两种接口运行相同的逻辑操作（例如获取交易），并测量请求和响应大小以及响应类型，来填写该表。

使用 curl 配合 --trace-ascii 或网络检查器来捕获 JSON-RPC 的原始字节。对于 gRPC，您可以使用 gRPC 客户端库的日志记录或像 grpcurl 这样的代理来检查二进制负载。请注意，gRPC 负载是二进制且可能不可读，但您可以测量其大小。目标是在您的特定环境中理解权衡。

请记住，网络条件、端点位置和提供商配置可能会影响结果。运行多次试验并取平均值。此方法不是基准测试；而是一种基于您自己的测量做出明智决策的方式。

• 操作：例如 GetTransaction
• gRPC 调用：例如 client.getTransaction({ digest })
• JSON-RPC 方法：例如 sui_getTransactionBlock
• 请求字节：测量原始负载大小
• 响应字节：测量原始负载大小
• 类型化与非类型化响应：gRPC 返回类型化对象；JSON-RPC 返回普通 JSON

Sui gRPC API 的限制与权衡

Sui gRPC API 功能强大，但也有其限制。首先，gRPC 端点和支持的服务因提供商和网络版本而异。并非所有 RPC 提供商都暴露 gRPC，而那些暴露的提供商可能只支持部分方法。在集成之前，请始终检查提供商的支持接口列表。OnFinality 的 API 服务页面记录了其 Sui 端点上可用的接口。

其次，API 正在演进。Sui gRPC 接口正在积极开发中，SDK 版本之间可能会出现破坏性变更。在项目中固定您的 SDK 版本以避免意外中断，并在升级前查看发布说明。Sui JSON-RPC 方法弃用文章指出 JSON-RPC 方法也可能发生变化，因此没有接口是完全静态的。

第三，gRPC 无法在没有代理的情况下直接从浏览器调用。浏览器不暴露 gRPC 所需的 HTTP/2 帧和二进制处理。Sui SDK 提供了 Web 安全路径，通常使用 gRPC-Web 或代理，但这增加了复杂性。如果您正在构建基于浏览器的 dApp，请考虑 JSON-RPC 或 GraphQL 是否对您的读取操作更简单。

最后，gRPC 是链的读/写接口，但它不能替代索引器进行历史聚合。如果您需要跨许多交易查询历史数据或计算聚合，GraphQL 或专用索引器更合适。gRPC 针对直接链访问进行了优化，而非分析查询。

• 提供商对 gRPC 的支持各不相同；在承诺之前请核实。
• API 正在演进；固定 SDK 版本并监控变更。
• 浏览器使用需要代理或 gRPC-Web；不能直接使用。
• 在需要历史聚合时，不能替代索引器。

排查常见的 gRPC 集成问题

在集成 Sui gRPC API 时，您可能会遇到与连接、序列化或版本不匹配相关的问题。本节介绍常见问题及其诊断方法。首先验证您的端点 URL 是否正确，以及您的提供商是否支持 gRPC。使用 grpcurl 进行快速测试可以确认连接并列出可用服务。

如果您收到 UNIMPLEMENTED 错误，您调用的方法可能不受提供商支持，或者您所针对的服务版本中不存在。请检查提供商的文档和 SDK 的 .proto 定义。如果您收到 DEADLINE_EXCEEDED 错误，请求超时；考虑增加截止时间或检查网络延迟。

序列化错误通常源于 Protobuf 定义不匹配。确保您的客户端存根与服务器从相同的 .proto 版本生成。如果您使用 Sui SDK，这会为您处理，但如果您自己生成存根，请保持同步。对于 JSON-RPC 对比，请记住 JSON-RPC 错误以带有 error 字段的 JSON 对象返回，而 gRPC 使用状态码。

有关 Sui RPC 的更多故障排除技巧，请参阅 Sui RPC 指南（RPC Assistant）。如果您正在从 JSON-RPC 迁移，Sui 交易效果和对象变更文章解释了如何解析交易结果，这在对比响应时很有用。

• 验证端点 URL 和提供商的 gRPC 支持。
• 使用 grpcurl 测试连接并列出服务。
• 检查 UNIMPLEMENTED 或 DEADLINE_EXCEEDED 状态码。
• 确保客户端和服务器之间的 Protobuf 定义匹配。

下一步：将 gRPC 集成到您的 Sui 应用

现在您已经了解了 Sui gRPC API 以及如何调用它，您可以开始将其集成到您的应用中。首先选择一个支持 gRPC 的提供商，例如 OnFinality，并获取端点 URL。查看 RPC 定价页面以选择满足您需求的计划。然后，安装 Sui TypeScript SDK 并在开发环境中试验类型化客户端。

在构建过程中，考虑 gRPC、JSON-RPC 和 GraphQL 之间的权衡。对于需要类型安全和流式传输的读密集型应用，gRPC 是强有力的选择。对于复杂的历史查询，GraphQL 可能更好。对于简单、广泛兼容的集成，JSON-RPC 仍然可行。您也可以混合使用接口：使用 gRPC 进行交易提交，使用 JSON-RPC 实现旧版兼容。

要加深理解，请探索相关的 OnFinality Learn 文章，例如 Sui GraphQL API 查询接口和 Sui queryTransactionBlocks 游标分页指南。这些资源将帮助您构建健壮、高效的 Sui 应用。有关网络和服务的完整列表，请访问 Sui 网络页面和 OnFinality Learn 中心。

• 选择支持 gRPC 的提供商并获取端点。
• 安装 Sui TypeScript SDK 并测试类型化客户端。
• 根据您的用例评估 gRPC 与 JSON-RPC 与 GraphQL。
• 探索相关的 Learn 文章以深入了解。