Fabric V2.5 LTS版本 SDK 由fabric-sdk迁移到fabric-gateway相关指南

链接 https://hyperledger.github.io/fabric-gateway/migration

Fabric V2.5 LTS版本 SDK 由fabric-sdk迁移到fabric-gateway相关指南

Hyperledger Fabric 客户端 SDKs 的迁移指南，主要讨论了如何将使用旧版 Hyperledger Fabric 客户端 SDKs 编写的现有应用程序重写为 Fabric Gateway 客户端 API。

Fabric Gateway 客户端 API 是旧版 SDKs 和 Fabric 编程模型的演进。API 结构和功能大致与旧版 SDKs 相同。包括：

Gateway：连接到 Fabric peer(s) 提供对区块链网络的访问。
Network：托管共享账本的区块链网络节点（类似于通道）。
Contract：部署到区块链网络的智能合约。
Submit transaction：调用智能合约交易函数以更新账本状态。
Evaluate transaction：调用智能合约交易函数以查询账本状态。
Chaincode events：接收由已提交的交易发出的事件以触发业务流程。
Block events：接收已提交到账本的区块。
Event checkpointing：持久化当前事件位置以支持事件恢复。

此外，页面还详细介绍了从旧版 SDKs 切换到 Fabric Gateway 客户端 API 时需要考虑的关键 API 和行为差异，包括 gRPC 连接、连接配置文件、钱包、背书要求以及事件重连等方面的变化。

这是一个技术性的文档，主要为开发者提供指导，以便他们更好地理解和使用 Fabric Gateway 客户端 API。

高级 API 用于连接 Gateway 实例，并提交或评估交易，这几乎保持不变。

对于涉及临时数据的更高级的交易调用，旧版 SDKs 在 Contract 对象上提供了一个 createTransaction() 方法，允许客户端应用程序指定额外的调用参数（参见 Go、Node 和 Java 文档）。Fabric Gateway 客户端 API 在 Contract 对象上提供了一个 newProposal() 方法来执行相同的功能（参见 Go、Node 和 Java 文档）。

关键差异

从旧版 SDKs 切换到 Fabric Gateway 客户端 API 时，需要考虑的关键 API 和行为差异包括：

gRPC 连接由应用程序管理，并且可以由 Gateway 实例共享。
不需要连接配置文件。
不需要钱包，应用程序选择如何管理凭证存储。
通常不再需要指定背书要求。
事件重连由客户端应用程序控制。
下面提供了这些项目的更多详细信息和建议。

gRPC 连接

在旧版 SDKs 中，每个 Gateway 实例都维护着用于评估和提交交易以及获取事件的网络节点的内部 gRPC 连接。每个 Gateway 实例可能会创建许多 gRPC 连接，而这些连接不会与其他 Gateway 实例共享。由于创建 gRPC 连接有相当大的开销，这可能会导致资源问题。

在 Fabric Gateway 客户端 API 中，每个 Gateway 实例使用单个 gRPC 连接到 Fabric Gateway 服务进行所有操作。Gateway 实例的 gRPC 连接由客户端应用程序提供，并且可以由多个 Gateway 实例共享。这允许客户端应用程序完全控制 gRPC 连接配置和资源分配。

API 文档包含了创建 gRPC 连接并使用此连接连接 Gateway 实例的示例，适用于 Go、Node 和 Java。

连接配置文件

Fabric Gateway 客户端 API 不使用常见的连接配置文件。相反，只需要 Fabric Gateway 服务的端点地址就可以建立将在连接 Gateway 实例时使用的 gRPC 连接。由于 Fabric Gateway 服务由 Fabric peers 提供，所以端点地址可能是连接配置文件中定义的 peer 地址之一。它也可以是负载均衡器或入口控制器的地址，该地址将连接转发到网络 peers，提供高可用性。

钱包

旧版 SDKs 提供了用于凭证管理的钱包。钱包执行两个功能：

持久性凭证存储。
基于凭证类型（例如，由硬件安全模块管理的身份）配置 Gateway 客户端。
使用 Fabric Gateway 客户端 API，存储凭证的机制是客户端应用程序的选择。应用程序可以继续使用旧版 SDKs 来访问存储在钱包中的凭证，或者可以使用不同的机制来存储和访问凭证。

要连接 Gateway 实例，应用程序只需提供一个 Identity 对象和一个签名实现。提供了辅助函数，可以从 X.509 证书创建一个 Identity 对象，也可以从私钥或 HSM 管理的身份创建一个签名实现。要使用其他签名机制，应用程序可以提供自己的签名实现。

背书要求

在使用旧版 SDKs 的更复杂的场景中，如涉及私有数据集合、链码到链码的调用或基于密钥的背书策略，客户端应用程序通常需要明确指定交易调用的背书要求。这可能是以指定链码兴趣、背书组织或背书 peers 的形式。

使用 Fabric Gateway 客户端 API，客户端应用程序通常不需要指定背书要求。Fabric Gateway 服务动态确定给定交易调用的背书要求，并使用最合适的 peers 来获取背书。

对于包含临时数据的交易提案，有两个显著的场景需要应用程序明确指定可能用于背书的组织：

Fabric Gateway 服务的组织无法背书交易提案。
执行对他们没有读取权限的私有数据集合的盲写的交易。
这些限制是为了确保不将私有数据分发给不应该访问的组织。

建议只在特别需要的情况下指定背书组织。

事件重连

在事件监听期间发生 peer 或网络故障的情况下，旧版 SDKs 会透明地尝试重新建立连接，并在成功重新连接后继续传递事件。Fabric Gateway 客户端 API 在请求下一个事件时将事件错误表面化到客户端应用程序。要重新建立事件，应用程序必须以适当的起始位置启动新的事件监听会话。

事件检查点跟踪当前事件位置，并可以用于在重新连接时恢复事件到正确的起始位置。