OCAP 超简易集成攻略(iOS 篇)

作者 Jonathan Lu (ArcBlock 团队移动开发工程师)

在之前的系列文章中,我们介绍了 OCAP 服务和它的Playground。现在我们已经知道如何在 Playground 里编写 GraphQL 的查询语句,以此来深入研究和探索区块链上的数据。假如我们在“游玩”中获得了一些灵感,发现了一些有趣的数据,并希望基于这些数据来开发一款移动应用的话,我们需要如何来实现呢?

其实实现起来非常简单!ArcBlock 专门为移动开发这提供了一整套工具,比如本文中要介绍的iOS SDK。使用这套工具,从移动端接入 OCAP 可以说是相当简单了。

假设我们想要创建一个 iOS 应用来展示一个“最富有的 Bitcoin 账户”列表,本文接下来的部分将会介绍如何使用 iOS SDK 来实现它。

安装 SDK

首先,我们需要将 SDK 安装到你的 Xcode 项目中。你可以使用CocoaPods或者Carthage来安装:

# Podfile
pod 'ArcBlockSDK', :git => 'https://github.com/ArcBlock/arcblock-ios-sdk.git'
pod 'Apollo', :git => 'https://github.com/ArcBlock/apollo-ios.git'
# Cartfile
github "ArcBlock/arcblock-ios-sdk"

生成 Swift 代码

现在先让我们暂时回到 OCAP Playground。

GraphQL 的一大特性是类型安全。在已知 schema 和查询语句的情况下,我们可以在运行时(runtime)之前确切地知道查询参数和返回数据的类型。因此,我们提供了一个 Swift 的代码生成工具,用它我们可以为我们的查询语句生成包装类(wrapper class)。SDK 将会使用这些包装类,并通过他们在编译时来保证数据的类型安全。

代码生成工具已经直接被集成到了 OCAP Playbook 中。在 Playbook 的右上角,你会看到Generate Codes的按钮。点击按钮后选择 Swift 作为目标语言,代码就会被生成好,并且输出到一个 API.swift 文件中。该文件会直接被下载到你的本机,你此时只需要将它拖拽到你的 Xcode 项目中即可。

Codegen in Playbook

你可以在此查看上图中的查询“最有钱的比特币账号”的 playbook。

安装 Xcode 文件模板

SDK 还提供了一些文件模板,供你生成一些新的使用 SDK 的特性的类。你可以使用一下的命令来安装这些模板:

wget http://ios-docs.arcblock.io/Templates.tar.gz; \
tar -xvf Templates.tar.gz --strip-components=1 --directory ~/Library/Developer/Xcode/Templates/File\ Templates/; \
rm Templates.tar.gz

初始化一个 ABSDKClient

现在我们来写一点代码吧!

ABSDKClient 是一个 GraphQL 的客户端,它负责组建和发送网络请求,解析请求结果,管理缓存等工作。你可以为每一个请求创建一个新的 ABSDKClient,也可以在整个应用中使用同一个 ABSDKClient:

// in AppDelegate.swift

var arcblockClient: ABSDKClient!

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    let databaseURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("ocap-demo-db")
    do {
        // initialize the AppSync client configuration configuration
        let arcblockConfiguration = try ABSDKClientConfiguration(endpoint: .btc, databaseURL: databaseURL)
        // initialize app sync client
        arcblockClient = try ABSDKClient(configuration: arcblockConfiguration)
    } catch {
        print("Error initializing ABSDKClient. \(error)")
    }
    return true
}

创建 ViewController

现在让我们来使用刚创建的 ABSDKClient 来发送我们的查询语句,并且展示返回的结果。我们需要使用刚才安装的文件模板来创建一个 ViewController。

New File New File

现在,一个 ABSDKTableViewController 和一个 ABSDKTableViewCell 的子类已经被创建好了。

配置 ViewController

下一步,我们需要配置一些 ViewController 的属性:

// in ViewController.swift

override func configDataSource() {
    // config the parameters for initiating data source

    let appDelegate = UIApplication.shared.delegate as! AppDelegate
    client = appDelegate.arcblockClient

    dataSourceMapper = { (data) in
        return data.richestAccounts?.data
    }
    pageMapper = { (data) in
        return (data.richestAccounts?.page)!
    }
    query = RichestAccountsQuery()
}

以上这段代码配置了四个属性:

  1. 使用哪个 ABSDKClient 实例,
  2. 定义了一个闭包(closure)来提取返回结果中需要用于展示的字段
  3. 定义了另一个闭包(closure)来提取返回结果中分页信息相关的字段
  4. 使用哪个查询语句的包装类

在 Cell 中展示返回结果的数据

再下一步,我们需要将返回结果中的数据绑定到 TableViewCell 上。

// in AccountListCell.swift

override func updateView(data: RichestAccountsQuery.Data.RichestAccount.Datum) {
    self.textLabel?.text = data.address
    self.detailTextLabel?.text = "Balance: " + String(data.balance!)
}

文件模板会同时创建一个 TableViewCell 的 XIB 文件,因此你也可以通过它来更灵活地设计 Cell 的样式。

运行应用

应用的开发到这里就已经完成了!你现在可以运行应用来看看效果了。

Screenshot

可以看到,你只需要写很少量的代码,而 SDK 会为你处理网络请求、解析结果、管理缓存、数据绑定以及分页。

完整的 Richest Account 实例代码可以在这里查看。

最后,如果你想要更灵活地定制你的 ViewController(例如使用 CollectionView 而不是 TableView),你也可以在数据或网络层使用我们的 SDK。您可以查看我们的 Data BindingClient 以及 Class Reference相关的文档。