(Swift) iOS Apps with REST APIs(一)

直接去编码对我们这些码农来说总是很有诱惑力的,但是如果我们事先先搞清楚要做什么,并做好计划,是不是可以让编码更顺利。或者至少我们得对需要编写的应用(App)有一些想法吧。Ok,下面让我们列出gist s这个应用(App)的需求,你可以根据你所要构建的应用进行修改。

重要说明: 这是一个系列教程,非本人原创,而是翻译国外的一个教程。本人也在学习Swift,看到这个教程对开发一个实际的APP非常有帮助,所以翻译共享给大家。原教程非常长,我会陆续翻译并发布,欢迎交流与分享。
另,原教程有第一章,讲述该教程及相关基础概念,感觉没有什么必要翻译,所以这里略过。有兴趣的可以自行上网去找原版教程。

App需求

直接去编码对我们这些码农来说总是很有诱惑力的,但是如果我们事先先搞清楚要做什么,并做好计划,是不是可以让编码更顺利。或者至少我们得对需要编写的应用(App)有一些想法吧。Ok,下面让我们列出gist s这个应用(App)的需求,你可以根据你所要构建的应用进行修改。

首先我们来列出来应用中有那些界面。当然我们有很多种方式可以完成这事,不过我喜欢先列出用户希望通过这款应用要完成那些事情,然后再进行界面设计就容易多了。

那么我们的用户会使用gists做什么呢?Gists是一些代码的片段,通过GitHub可以分享给其他用户。因此用户通过gists可能需要以下功能:

  1. 查看公共的gists库列表,看看有哪些新鲜的东东;
  2. 查询感兴趣的gists库,通常是通过编程语言进行查询;
  3. 收藏/关注一个gists库,后面可以查看;
  4. 查看自己所收藏/关注的gists库列表;
  5. 查看自己的gists库,保存一些常用的代码,以后不用每次都要再敲一遍;
  6. 查看公共、自己或者收藏的gists库的详情;
  7. 创建新的gists库;
  8. 删除自己的gists库。

列出你的应用中的任务或者用户故事。与gistsApp做一个对比,对比时重点关注一下不同的对象(如:收藏、用户,及gists库)以及动作(如:查看列表、查看一个对象的详情、增加、删除等)。

或许你列表很长,那么这时候你需要考虑一下是否都需要在第一版中实现,如果不是,可以将哪些功能分离到下一个版本中实现。

现在评估你的列表中的每一项功能,判断哪些是需要在第一版中实现。现在说不定你已经开始想设计第二版了。但是,一个可以运行的应用要远比一个无限期延迟发布的完美应用要好。

匹配功能与API端点(endpoint)

接下来,我们为功能列表中的每一项,找出如何使用API接口获取需要显示的数据。我们会检查Github GISTs API文档,然后为每个功能找到相应的API端点(endpoint)。我们也会标出哪些API端点需要进行特殊处理的,比如身份验证或分页。

公共gists库列表

GET /gists/public

不需要身份验证。如果我们查看20条以后的,那么需要使用分页来加载更多数据。

查询Gists库

Github没有为此提供接口。我们的应用如果没有查询功能还是非常不错的,所以就先不做这个功能。

收藏/取消收藏Gists库

PUT /gists/:id/star
  DELETE /gists/:id/star

需要身份验证。

收藏列表

GET /gists/starred

需要身份验证。

我的Gists列表

有两种方式获取一个用户的gists列表:

GET /users/:username/gists

如果已经验证,可以使用:

GET /gists

查看Gist详情

我们可以通过列表视图传递gists的详情数据给详情页面,如果没有,则可以通过下面来获取:

GET /gists/:id

如果我们要判断一个gists是否被收藏,可以使用:

GET /gists/:id/star

创建Gists

POST /gists

如果要创建一个用户自己的Gists库需要先进行身份验证,否则所创建库的创建者为匿名。
创建时提交的JSON数据结构如下:

{
  "description": "gist库的描述",
  "public": true,
  "files": {
    "file1.text": {
      "content": "文件内容,或者代码"
    }
  }
}

删除Gists

DELETE /gists/:id

需要身份验证。

以上就是我们需要的所有端点(endpoint)。即使没有提供查询相关的API,但使用这些API来编写这个示例应用还是足够的。

分析每一项功能并列出相应的API端点(endpoint)或iOS功能都是必须的。我们要确保这些API是有效的,如果不是并且它们是由你们自己团队来维护的,那么赶快进行申请,以便留有充足的时间来实现这些API。

用户界面

接下来,我们来设计我们的应用以便让用户使用起来。我们将分析每一个任务并给出相应的使用方式。下面是我按照接口的使用对功能进行重新排序。

认证流程

当用户所操作的功能需要身份认证后才能使用时,那么首先我们将进行用户身份认证检查,如果没有通过,则启动登录流程让用户登录。

如果你的应用中有许多功能允许用户在未登录之前使用,那么或许你希望延迟用户的登录。因此对于哪些需要登录后才能调用的接口,你必须在调用之前检查用户是否登录过。

公共Gists列表

首页是公共Gist的列表(使用表格视图table view)。

我的收藏

从公共列表,用户可以切换到我收藏的列表。

我的Gists

从公共列表或我收藏的用户都可以切换到我的Gists。
上面三个列表很相似,是否我们可以使用一个带有选择器的表格视图,用户可以通过选择来切换这三种视图。

查看Gists详情

当用户在列表中点击其中一个Gists后,我们将转换到另外一个不同的视图。在这个视图中将详细的列出了Gists的信息(描述及文件名称)以及可以让用户查看文件的内容。同时,界面中也会显示我们是否已经收藏过该Gists。

收藏/取消收藏Gists

在详情页面中,我们将显示收藏的状态,并可以通过点击进行收藏或取消收藏。

新建Gists

我的Gists列表视图的右上角有一个+按钮。点击这个按钮将显示一个录入表单,用户可以用来创建一个新的Gists,表单中需要录入的信息有:

  • 描述:一段文本;
  • 是否公开:布尔值;
  • 文件名称:文本;
  • 文件内容:文本。
    为了保持简单,1.0版中只允许在Gists中创建一个文件。

删除Gists

我的Gists视图中可以通过滑动删除一个Gists。

检查你的功能列表并给出用户界面,以便用户可以完成这些功能。

API需求

当我们梳理这些用户功能时,会发现有些需求的API并不是那么明显。因此,我们需要仔细阅读,以便整理出一个列表清单。

认证

当未认证时,我们可以读取公共Gists,并可以匿名创建一个Gists。但是,当需要读取或编辑私有的Gists时,则必须进行OAuth认证。请参阅Github Gists API文档

因此,我们需要对用户进行身份验证。对于集成,首选的是使用OAuth2.0。该接口使用了用户名/密码进行验证,但是我们不需要为这些敏感数据担心。因为,OAuth2.0不会让我们看到用户名和密码,而交互的只是用户的应用令牌(token)。我们将安全的保存OAuth的令牌。

检查一下你的API认证要求。在后面的认证章节我们会实现OAuth2.0认证、基于令牌的认证,以及最基础的用户名/密码认证。

设置Accept报头(Accept Header)

在Github API文档中描述到,我们必须设置请求的Accept报头,类似下面:

Accept: application/vnd.github.v3+json

也就是说,你不设置的话,返回的结果将不是你所期望的。所以,我们会在后续的开发中进行处理。

查看你的API文档,确认还有哪些需要设置的。

在iOS9中,苹果引入了App Transport Security(ATS)概念,具体参见这里ATS要求使用SSL进行数据传输,这对实施来说是非常挑剔的。可悲的是,现在很多服务器是不满足这项要求的。但,GitHub的gist API是满足ATS这项要求的,因此我们不必添加额外的处理。

如果你在iOS9中调用自己的API出现了SSL错误,你需要添加ATS的错误处理。你可以在下一章节中看到如何解决的细节。你可以用章节中的代码尝试调用你的服务器所提供的一些简单API看是否有SSL错误。

制定开发计划

现在我们已经知道我们要做什么,以及怎么做。那么我们将逐步实现这些功能,从而完善这个APP。

  • 创建我们的APP,并增加一个表格视图用来显示公共Gists列表;
  • 增加自定义报头(header);
  • 加载表格视图中的图片;
  • 当用户滚动到底部时加载更多的Gists;
  • 增加下拉刷新功能;
  • 增加认证,让用户可以切换到我的Gists及我的收藏列表;
  • 创建Gists的详情页面;
  • 在详情页面增加收藏/取消收藏功能;
  • 增加删除和新建功能;
  • 增加无网络情况时的处理。

按实现的顺序列出你的视图及功能。尝试与Gists App的开发顺序进行匹配。如果你的API都需要身份认证才能够调用,那么你需要先跳到认证章节,然后再回来。如果你的所有请求都需要添加自定义报头,那么需要先跳到报头章节。

我们现在已经列出了应用的基础需求,也知道下面该怎么开始。但,在开始动手之前,让我们先花点时间了解一下在Swift中如何进行web请求,以及JSON解析,以免后面陷入这些细节之中。