使用 IBM Blockchain Platform VSCode 扩展开发智能合约

了解如何使用 IBM Blockchain Platform 的 VSCode 扩展来简化智能合约的开发、测试和部署过程。完成本教程后，您将了解如何使用 VSCode 在本地 Hyperledger Fabric 网络上快速开发，演示和部署区块链应用程序。本教程假设您对 Hyperledger Fabric 有一些基本了解。

学习目标

• 安装 IBM Blockchain Platform VSCode 扩展
• 创建一个新的 JavaScript 智能合约
• 打包智能合约
• 创建、探索和了解 Hyperledger Fabric 网络
• 在本地 Hyperledger Fabric 实例上部署智能合约
• 使用 Node.js SDK 与部署的智能合约包进行交互

前提条件

您需要安装以下软件才能使用扩展：

• Node v8.x 或更高版本以及 npm v5.x 或更高版本
• Yeoman (yo) v2.x
• Docker v17.06.2-ce 或更高版本
• Docker Compose v1.14.0 或更高版本
• VSCode 1.28.2 或更高版本

如果您使用的是 Windows，还必须确保满足以下要求：

• 您的 Windows 版本支持 Hyper-V 和 Docker：
  • Windows 10 Enterprise、Pro 或 Education，并且安装了 1607 周年更新或更高版本的更新
• Docker for Windows 配置为使用 Linux 容器（这是默认设置）
• 已经通过 windows-build-tools  安装了适用于 Windows 的 C++ 构建工具
• 已经通过 Win32 OpenSSL  安装了 OpenSSL v1.0.2
  • 安装正常版本，而不是标记为 "light" 的版本
  • 在 32 位系统上，将 Win32 版本安装到 C:\OpenSSL-Win32 中
  • 在 64 位系统上，将 Win64 版本安装到 C:\OpenSSL-Win64 中

您可以通过从终端运行以下命令来检查安装的版本：

• node --version
• npm --version
• yo --version
• docker --version
• docker-compose --version

预估时间

安装必备软件后，大约需要 30 到 45 分钟才能完成。

步骤

第 1 步. 入门

您要做的第一件事是安装 IBM Blockchain Platform VSCode 扩展。为此，您需要安装最新版本的 VSCode；要了解您是否具有最新的 VSCode 扩展，可转至 Code>Check for Updates。如果此时 VSCode 崩溃（我就遇到了这种情况），这可能意味着您没有最新版本。如果您的 VSCode 崩溃，可查看下面的故障排除部分。否则，更新您的 VSCode，完成后，单击屏幕左侧边栏中的 extensions。在顶部的扩展市场中搜索 IBM Blockchain Platform。单击 Install，然后单击 reload。现在，您应该能够使用该扩展了！

第 2 步. 创建一个新的智能合约项目

执行以下操作来创建智能合约项目：

1. 单击新下载的 IBM Blockchain Platform 扩展。它应该是一直位于左侧边栏底部的扩展。
2. 接下来，使用键盘快捷方式 Shift+CMD+P 调出命令面板。从下拉菜单中选择 IBM Blockchain Platform: Create Smart Contract Project 。
3. 在下拉菜单中单击 JavaScript 。
4. 单击 New Folder ，然后根据需要命名项目。我把我的项目命名为 demoContract。
5. 单击 Create ，然后单击 Open 打开您刚刚创建的新文件夹。接着，在下拉菜单中单击 Add to Workspace 。
6. 一旦此扩展打包了您的合约，您便可以打开 lib/my-contract.js 文件来查看智能合约代码搭建。做得不错！

第 3 步. 修改智能合约

在 lib/my-contract.js 文件中，直接复制并粘贴以下代码：

'use strict';

const { Contract } = require('fabric-contract-api');

class MyContract extends Contract {

  //update ledger with a greeting to show that the function was called
  async instantiate(ctx) {
    let greeting = { text: 'Instantiate was called!' };
    await ctx.stub.putState('GREETING', Buffer.from(JSON.stringify(greeting)));
  }

  //take argument and create a greeting object to be updated to the ledger
  async transaction1(ctx, arg1) {
    console.info('transaction1', arg1);
    let greeting = { text: arg1 };
    await ctx.stub.putState('GREETING', Buffer.from(JSON.stringify(greeting)));
    return JSON.stringify(greeting);
  }

}

module.exports = MyContract;

注意：.gifs 可能与以上智能合约并不 完全 相同，但您的 lib/my-contract.js 文件中现在应该有这个文件！

我们来看看您刚才定义的函数。instantiate 函数可创建一个问候语对象，然后使用 GREETING 键将它存储在账本中。transaction1 函数获取 Hyperledger Fabric 上下文和参数 arg1，此参数用于按照用户定义的方式来存储问候语。ctx.stub.putState 方法用于在账本上记录 greeting，然后您可以返回此对象。保存文件并继续！

第 4 步. 打包智能合约

既然您已经创建了智能合约，并了解了定义的函数，现在该进行打包了，这样就可以把它安装在对等节点上。

1. 使用 Shift+CMD+P 打开命令面板，然后选择 package smart contract 。
2. 在左侧边栏中，单击 IBM Blockchain Platform 图标（看起来像一个正方形）。在左上角，您将看到所有智能合约包。如果一切进展顺利，您应该能够看到 [email protected]。

第 5 步. 安装智能合约

您已经完成了超过一半的操作了。现在到有趣的部分了！让我们将这份合约安装在对等节点上！ 为此，您必须先连接到 Hyperledger Fabric 网络。VSCode 扩展附带的网络非常适合开发 - 它提供了开发和测试合约所需要的最少资源。

以下 Docker 容器在本地机器上启动，每个容器在网络中都扮演不同角色：订购者、证书颁发机构、CouchDB 和对等节点。

单击编辑器左侧的 IBM Blockchain Platform 扩展来启动网络。这是一个看起来像正方形的图标。

1. 单击该扩展后，您应该会在编辑器左侧看到 LOCAL FABRIC OPS 。在 LOCAL FABRIC OPS 右侧，您应该看到三个点的符号。单击此符号，然后单击 Start Fabric Runtime 。

   您的扩展现在将配置 Docker 容器，这些容器在网络中充当节点。在配备完成后，您应该会在 LOCAL FABRIC OPS 下看到 Smart Contracts 部分。

2. 在 Smart Contracts 下单击 + Install 。
3. 接下来，该扩展将询问您要在哪个对等节点上安装智能合约。选择 peer0.org1.examplee.com
4. 该扩展将询问您要安装的包：选择 [email protected]。如果一切顺利，您应该 在右下角看到如下通知： Successfully installed on peer peer0.org1.example.com  就这么简单！做得不错！

第 6 步. 实例化智能合约

这是真实的测试 - 您的智能合约是否会正确实例化？让我们来一探究竟……

1. 在 Smart Contracts 下，您将看到某一部分显示 Instantiated 。单击 + Instantiate .
2. 该扩展随后将询问您在哪个通道上实例化智能合约 - 选择 mychannel 。
3. 该扩展接着将询问您实例化哪个合约和版本 - 选择 demoContract @ 0.0.1。
4. 该扩展还将询问要调用哪个函数 - 输入 instantiate
5. 接下来，该扩展将会询问要使用的参数。没有任何参数，所以可直接按 Enter 键。

该扩展将执行一些操作，然后在右下角，您应该看到合约已经成功实例化。太棒啦！

第 7 步. 导出连接详细信息

此时，您需要开始与 Fabric 实例进行更密切的交互。您需要向证书颁发机构证明您获准 在网络上创建数字身份。这可通过向证书颁发机构显示您的证书和私钥来完成。

1. 在本教程的后面，我们将查询网络。为此，我们需要一些脚本。在智能合约目录之外克隆以下 Github 存储库，获取查询网络所需的必要脚本。

   $ git clone https://github.com/horeaporutiu/VSCodeTutorialBlockchain.git

2. 右键单击 VSCode 中智能合约目录下的空白区域， 然后选择 Add folder to workspace ，从而将此文件夹导入 VSCode 工作空间。 找到最近克隆的文件夹 VSCodeTutorialBlockchain 并双击。
3. 在 VSCode 中，单击左侧边栏中的 IBM Blockchain Platform 扩展。
4. 在 LOCAL FABRIC OPS 下，单击 Nodes 。右键单击 peer0.org1.example.com 节点。选择 Export Connection Details 。
5. 该扩展将询问要将连接配置文件保存到哪个文件夹。选择 VSCodeTutorialBlockchain directory 。
6. 如果一切顺利，应显示如下内容：

   Successfully exported connection details to
   /Users/[email protected]/Workdir/VSCodeTutorialBlockchain/local_fabric

第 8 步. 提交相关交易

您已经将合约实例化，并将密钥导出到我们的钱包 - 现在该怎么办呢？ 现在该在智能合约中实际调用函数了！为此， 您可以使用 VSCode 扩展。

1. 在 LOCAL FABRIC OPS 下，您应该看到 FABRIC GATEWAYS 。
2. 单击 local_fabric ，然后单击 [email protected] 。
3. 如果一切顺利，您应看到一条如下内容的通知： Connecting to local_fabric 。
4. 接下来，在 FABRIC GATEWAYS 和 Channels 下，您应该会看到 mychannel 。单击将其展开。然后展开 [email protected] 。您应该会看到两个函数： instantiate 和 transaction1 。
5. 右键单击 transaction1 ，然后选择 submit transaction。对于参数，输入 "hello"。

做得不错！您已成功将交易提交到 Fabric 网络，并且已经更新了账本！

第 9 步. 更新智能合约

在上一步，您使用传入了键和值的 putState API 更新了账本。键刚好是 "GREETING"，值刚好是该对象。

{
  text: 'hello'
}

最后，您应该学习如何查询 - 如何从账本中检索数据。您需要使用 getState API 来完成此任务，此 API 获取一个键，然后返回与此键相关联的值（如果找到的话）。

让我们向 demoContract 中添加一个查询函数。

1. 复制以下代码并粘贴到 lib/my-contract.js 文件中：

   'use strict';
   
   const { Contract } = require('fabric-contract-api');
   
   class MyContract extends Contract {
   
    //update ledger with a greeting 
    async instantiate(ctx) {
      let greeting = { text: 'Instantiate was called!' };
      await ctx.stub.putState('GREETING', Buffer.from(JSON.stringify(greeting)));
    }
   
    //add a member along with their email, name, address, and number
    async addMember(ctx, email, name, address, phoneNumber) {
      let member = {
        name: name,
        address: address,
        number: phoneNumber,
        email: email
      };
      await ctx.stub.putState(email, Buffer.from(JSON.stringify(member)));
      return JSON.stringify(member);
    }
   
    // look up data by key
    async query(ctx, key) {
      console.info('querying for key: ' + key  );
      let returnAsBytes = await ctx.stub.getState(key);
      let result = JSON.parse(returnAsBytes);
      return JSON.stringify(result);
    }
   
   }
   
   module.exports = MyContract;

   此代码添加了一个 addMember 函数，用于获取用户输入的参数，如电子邮件、姓名、地址和电话号码，并将该数据作为键/值对保存在账本中。

   此代码还添加了 query 函数；此函数接受一个参数，也就是要查找的键。此函数返回与给定键关联的值（如果有的话）。

2. 更新 package.json 文件，包含版本号的第 3 行现在应该为：

   "version": "0.0.2",

   保存该文件。

3. 要将现有智能合约升级到新版本，可在 LOCAL FABRIC OPS
   下展开 Instantiated ，直至看到 [email protected] 。然后，右键单击 demoContract 并选择 Upgrade Smart Contract 。
4. 该扩展将询问您要执行升级的版本。选择 demoContract 。
5. 该扩展将询问要在哪个对等节点上安装智能合约，选择 peer0.org1.example.com
6. 该扩展将询问要调用的函数。输入 instantiate 。
7. 该扩展将询问要传递的参数。将此项留空，然后按 enter  键。在进行大量计算（需要一点时间）之后，如果 一切顺利，您应该会在右下角看到如下通知： Successfully upgraded smart contract 。

第 10 步. 提交更多交易

既然您已经更新了智能合约，在 FABRIC GATEWAYS 下展开 Channels ， 然后展开 mychannel ，应该会看到 [email protected] 。

1. 接下来，展开 [email protected] 以查看更新智能合约 my-contract.js 时使用的函数，也就是 instantiate、addMember 和 query。
2. 右键单击 addMember ，然后单击 Submit Transaction

   。对于参数，复制并粘贴以下内容：

   [email protected], Ginny Rometty, Wall Street NY, 1234567890

   在输出中，您应该会看到以下内容：

   Submitting transaction addMember with args Ginny Rometty, Wall Street NY,
                   1234567890, [email protected]

   让我们再添加一个成员，这样就需要重复以上步骤，但对于参数，只需复制并粘贴以下内容：

   [email protected], Arvind Krishna, Broadway Street NY, 1231231111

   做得不错！我们就要大功告成了！

第 11 步. 查询账本

现在就是您期盼已久的时刻了！我们来实际看看账本中写入了哪些内容。为此，我们将使用 VSCodeTutorialBlockchain 文件夹中的 query.js 文件。

1. 看一下 VSCodeTutorialBlockchain 目录中的 query.js 文件。这个文件与 invoke.js 文件很相似，但有一个主要区别：

   let response = await
   contract.evaluateTransaction('query', 'GREETING');

   这个主要区别就在于，在这个文件中，您将使用 evaluateTransaction API，这个 API 不会将交易发送到订购服务 -- 因此，也就不会更新账本。这一点非常重要：在 invoke.js 文件中，您将交易提交到订购服务，交易将全部 写入到账本中 ，但在 query.js 文件中，您将不会更新账本。

2. 在 VSCode 中使用终端导航到 VSCodeTutorialBlockchain  文件夹。在此处，使用以下命令 安装必需的依赖项：

   VSCodeTutorialBlockchain$ npm install

3. 接下来，使用以下命令运行 query.js

   ：

   VSCodeTutorialBlockchain$ node query.js

   您应该会看到以下输出：

   Connected to Fabric gateway.
   { text: 'Instantiate was called!' }
   Disconnect from Fabric gateway.
   done

4. 接着，查询 Ginny Rometty。将以下行：

   let response = await contract.evaluateTransaction('query',
                   'GREETING');

   更改为：

   let response = await contract.evaluateTransaction('query',
                   '[email protected]');

   您的输出应如下所示：

   VSCodeTutorialBlockchain$ node query.js
   Connected to Fabric gateway.
   {"address":" Wall Street NY","email":"[email protected]","name":" Ginny Rometty","number":" 1234567890"}
   Disconnect from Fabric gateway.
   done

5. 最后，查询 Arvind。将请求修改为如下所示：

   let response = await contract.evaluateTransaction('query','[email protected]');

   输出应类似以上结果，只不过显示了 Arvind 的数据。

第 12 步. 测试合约

IBM Blockchain 扩展可以对功能进行测试，并且可以通过 UI 来完成。单击左侧的 IBM Blockchain Platform 扩展图标。

1. 在 FABRIC GATEWAYS 和 Channels 下，展开 mychannel ，然后右键单击最新智能合约 [email protected]，并选择 Generate Smart Contract Tests 。
2. 该扩展将询问您要以哪种语言生成测试文件。选择 JavaScript 。
3. 一旦该扩展生成了测试，您便可以从 demoContract 目录运行 npm 测试，也可以通过 VSCode UI 单击 [email protected] 文件中的 run test  按钮，如 gif 中所示。

结束语

很棒！您已经学习了如何使用 Hyperledger 的最新 API 来创建、打包、安装、实例化以及调用智能合约。从现在开始， 您已经熟悉了区块链的网络方面， 因而能够专注于开发智能合约以及更新 my-contract.js 文件。您还可以使用 VSCode、 Node.js 和 Docker 来成功调用和更新您的账本。如果遇到任何 Bug，请务必与我联系 -- 对这篇文章发表评论，我将会予以纠正。非常感谢您阅读本教程。希望您能喜欢！Horea 区块链已横空出世！

参考资源

• 查看 IBM Blockchain Platform Extension for VSCode ，了解更多详情。
• Code Pattern: 使用 IBM Blockchain Platform Extension for VS Code 创建一个全球金融区块链应用
• Hyperledger Fabric 实践与分析

本文翻译自： Develop a smart contract with the IBM Blockchain Platform VSCode extension （2018-11-20）