客户端 SDK

目的与范围

客户端 SDK 提供了一个 Rust 库，用于通过 GraphQL API 与 fuel-core 节点进行程序化交互。它使外部应用程序能够查询区块链状态、提交交易、监控交易状态以及与 fuel-core 网络进行交互。本文档涵盖了 Rust 客户端实现及其 GraphQL 接口。

有关 GraphQL API 架构和端点详细信息，请参阅 GraphQL Schema。有关 fuel-core 节点的部署和操作方面，请参阅 Deployment and Operations。

架构概述

客户端 SDK 构建于基于 GraphQL 的架构之上，该架构在客户端应用程序和 fuel-core 节点之间提供类型安全的通信。

客户端 SDK 架构

来源：crates/client/src/client.rs247-255 crates/client/src/client.rs460-584

核心组件和职责

来源：crates/client/src/client.rs225-244 crates/client/src/client.rs362-405

FuelClient 接口

FuelClient 结构体是与 fuel-core 节点进行所有交互的主要入口点。它管理 HTTP 连接、一致性策略，并提供所有支持操作的方法。

客户端初始化

客户端可以从各种输入格式创建

来源：crates/client/src/client.rs257-301 crates/client/src/client.rs327-353

一致性策略

该客户端支持两种一致性策略来处理区块高度要求

策略	描述	用例
`ConsistencyPolicy::Auto`	自动跟踪响应中的最新区块高度	大多数应用程序的默认设置
`ConsistencyPolicy::Manual`	使用手动指定的区块高度	历史查询，特定区块要求

来源：crates/client/src/client.rs193-223

核心操作

该客户端为所有主要区块链操作提供了方法

交易操作

submit() - 将交易提交到交易池
submit_and_await_commit() - 提交并等待最终确定
dry_run() - 执行交易而不提交
estimate_predicates() - 估算谓词的 Gas 使用量
assemble_tx() - 组装交易，自动处理输入/输出

查询操作

transaction() - 按 ID 获取交易
transactions() - 获取分页交易
block() - 按 ID 或高度获取区块
chain_info() - 获取链信息
node_info() - 获取节点状态和对等信息

资产和余额操作

balance() - 获取特定资产的账户余额
coins() - 获取账户的可花费币种
contract_balance() - 获取合约资产余额

来源：crates/client/src/client.rs854-895 crates/client/src/client.rs701-733 crates/client/src/client.rs640-663

GraphQL Schema 和类型系统

Schema 定义结构

GraphQL schema 定义了客户端可用的完整 API 表面

来源：crates/client/assets/schema.sdl1528-1532 crates/client/assets/schema.sdl945-1172

类型转换架构

客户端实现了全面的类型转换系统，用于 GraphQL schema 类型和原生 Rust 类型之间的转换

来源：crates/client/src/client/schema/tx.rs137-144 crates/client/src/client/types.rs169-266

高级特性

分页支持

该客户端为大型结果集提供了全面的分页支持

来源：crates/client/src/client/pagination.rs1-50 crates/client/src/client/schema/tx.rs95-108

订阅支持

通过启用 subscriptions 功能，客户端支持通过 Server-Sent Events 进行实时更新

交易状态监控

订阅架构

来源：crates/client/src/client.rs458-584 crates/client/src/client.rs888-943

交易组装

assemble_tx() 方法提供了自动化的交易构建，包括输入选择和费用计算

组装流程

来源：crates/client/src/client.rs813-851 crates/fuel-core/src/schema/tx.rs346-513

错误处理

该客户端实现了全面的错误处理，并提供特定的错误类型

错误类型	描述	来源
`ConversionError`	类型转换失败	Schema 到原生类型的转换
`TransactionFromBytesError`	无效的交易字节	交易反序列化
`UnknownVariant`	未知的 GraphQL union 变体	Schema 演化处理
`MissingField`	必需字段缺失	GraphQL 响应验证
`BytesLength`	无效的字节数组长度	二进制数据验证

来源：crates/client/src/client/schema/schema.rs1-50 crates/client/src/client.rs316-325

集成模式

基本交易流程

历史状态查询

当节点启用了 --historical-execution 时，客户端支持查询历史区块链状态

来源：crates/client/src/client.rs709-734 crates/fuel-core/src/schema/tx.rs544-587