iOS面试收集restful架构设计与重构

从App角度看API (RESTful) 设计

2015-12-22  本文已影响3732人  码懂
要API，不要做外星人 (图片来自网络) 
首发：http://www.jianshu.com/p/ace1428888ca

做了10多年的桌面和逻辑模块的开发，两年前才开始接触互联网这一块，说起来对RESTful API是没有太多经验的。
公司app搭建之初，前后端通力合作，期间同不少后端同事就API的设计都有过沟通交流；到现在app上线也要快满一年了，不久前进行了一次大改版，部分API也从v1升级到了v2，觉得有些经验，可以总结一下。

一. API设计的一些基本原则

  1. API是自述的
    大多数我看的资料所写的Intuitive（直观的、直觉可理解的），也有些写Descriptive（描述性的），我将其命名为“自述”。一个API有自述性，也就是说看到API的URL，就知道这个API是要干嘛；且这个API的返回值中的字段，又能很好的解释其返回的内容。
    虽然API文档是不可或缺的，但是如果看到API的URL和API的返回值字段就知道这个API的功能作用，多好！
    （注：下文有实例）

二. 我亲历、验证了的API设计Tip

1. 使用 JSON Object (Dictionary/HashMap)

JSON格式简美，是现在流行的通信格式。上一句是废话，其实我想说的是，相对于Array，使用Object （Obj-C/Swift中可与Dictionary互转，Java中可与HashMap互转） 能够让API有更大的腾挪空间。

比如有个搜索视频关键字，返回视频列表的API，要求能够让客户端对视频列表进行分页浏览。最开始设计返回的是JSON Array，在HTTP header中带入总页数供客户端进行分页处理。

这个API的设计简明直白：你需要列表，我返回Array。因此服役了不短的时间。
后来需求变了，要求在用户搜索特定关键字或者出现特定视频的时候，在页面上加入特殊的Label。然后，然后...不得不重新设计了v2版本的API。为了继续服务老版app，后台需要维护两套API。烦！

若最开始这个API就设计成JSON Object，则有好处如下：

  1. 总页数不必带在HTTP header中，整个API的信息都集中在Object内。即是我上面提到的“API的自述性”
  • 对于新的需求，增加一对Key-Value即可，老版app和新版app采用同一个API，不需要额外的逻辑去维护两套API。即是我上面提到的“API的兼容和扩展性”
2. API不要返回后台数据库的index（如自增长ID）

前端对后台资源进行引用时，常需要一个唯一标识，比如xxID之类。当时后台小伙极力说服我使用数据库中的自增长ID，被我否决了。
一般而言，生成一个全局唯一的UUID或者标识性String都是不错的选择。

前些时则发生了另外一件事，很能说明些问题。有个资源文件比较庞大，我采取了如下的使用和更新策略：

  1. app内用本地文件的方式预存一份数据 (version=1)
  • 当app内需要用到这个数据时，先查找缓存，再查找本地文件，这样可以保证以最快的速度获取到数据进行展示
  • 同时，app走API向后台获取这个文件的新版本（带入version=1的参数）
    • 若数据没有更新的版本，后台返回空
    • 若数据有新版本，则下载并缓存

这种方法对数据量大、更新不频繁、后台对数据容忍性大的API非常适用。
可惜上线前突然bug了。最后查找原因，发现是因为之前都在测试服务器上测试，本地文件保存的数据中含有后台数据库的自增长ID。上线前在production服务器上一跑，查无此人。

上面说了一个不使用后台数据库自增长ID的具体例子。也即是前面提到的“API的抽象性”。

3. API获取资源要精准完备

由于业务逻辑的需要，常规的API设计可能会有疏漏时，需要根据情况仔细斟酌。

比如有个网站搜集了过去一年和未来半年全世界所有的公开课、讲座和会议信息，当用户进行浏览时，默认显示当前时间点以后的50条信息；当用户往下翻至第50条时，继续加载后50条；当用户往上翻至第一条并pull整个列表时，前向加载过去的50条信息。

初看起来这个API和前面提到的视频列表很相似，但是存在如下条件：

因此，传统的分页方式肯定是不行的。中间构思过以第一次浏览时间点作为基准的设计，也被找出了n多问题。

最终我们采用的是以UUID为基准的设计。

  • 当用户第一次浏览时，会根据用户的访问时间点，对所有条目进行时间+自增长ID的二次排序，并返回前50条
  • 当用户向下翻页时，提供最后一个条目的UUID作为参数，后台搜索到其时间和自增长ID，然后同样以时间+自增长ID作为过滤条件进行排序，并返回前50条
  • 当用户向前翻页时，提供第一个条目的UUID作为参数，同上。

举这个例子，主要是想说设计API一定要仔细谨慎，使其具有完备性。但是，让人遗憾的是，这个API其实在某些情况下还是会有遗漏，对照前面的3个条件，你能发现问题吗？

4. API默认值的意义

iOS平台编程中，UIView类提供了hidden属性，用于隐藏此窗口。为何用hidden而不用shown呢？因为窗口默认是显示的，对应着属性的默认值NO(false)。
这样的设定同样适用于API的设计。

比如app中采用统一的广告策略：使用webview加载广告页。但是广告页的展示和动画则可能有两种形式：

  1. 广告页有navigation bar (push进来或者包在navigation bar中被present出来)，并显示navigation title。
  2. 广告页被全屏present出来

绝大多数情况下，广告页都采用第一种方案展示，但是特殊的广告页可能会要求采用第二种方案展示(比例较低)。
后台API提供广告URL，以及展示广告页的形式。

这个例子中，显示navigation bar的广告页就是默认情况，因为显示navigation bar的概率大。
在我明了上面这段分析之前，API是这么设计的：

{ URL: "https://xxx", nav_title: "NOT Ads" }  // 糟透了

这里，nav_title承担了双重责任：

初看起来这样的设计好像也挺不错。但是由于nav_title的默认值（nil）并不对应广告页的默认展示形式（带navigation bar），可能无法应对新的需求变更。
比如以后因为要加入新的展示形式而需要废弃掉nav_title、替换成别的字段时，会发现nav_title删不得。WHY？因为老版本的用户必须依赖于这个参数的非默认值，简直太糟糕了。
至于如何设计这个API才算好，那就见仁见智了。

5. 全局HTTP header

全局HTTP头很金贵，因为一旦设置，则所有的API都会带上，增加数据量+消耗流量。一般来说，用户信息、平台和版本信息等都是不可缺少的，更多的可以参看我后面给出的链接。
我这里要提醒的是，现在的App设计中，总难保不打开一些web页面，最好记得在webview的HTTP header中做同样的处理哟~

6. 常量Key

上文提到API返回最好是一个JSON Object (Dictionary/HashMap)，便于扩展。本节标题里说的Key，就是键值对（key-value）中的key，而常量就是我们通常意义上的const。也就是说，我们用于通信的API接口，其key最好能写成const。

比如app请求后台的广告业务数据，参数是placementID，后台根据配置，获取该placementID所对应的广告展示类型adType，然后把数据adData返回给app。

一种意见是用placementID做为key，客户端根据placementID来获取广告，感觉十分直接。结构如下：

{"ads" : {placementID: adData}}

但是app端在这里需要额外的判断adData所隐含的展示类型，认为不妥

另一个种意见是以广告的展示类型adType作为key，app端根据UI的展示方式获取数据，贴近实现。结构如下：

{"ads" : {adType: adData}}

但是这种方法一是丢掉了placementID的信息，扩展性上存在问题（比如一次性请求多个placement的广告时）；二是广告的展示类型可能会随业务变化，作为key时同样有兼容性的问题。

但是按照本节的标题所建议的设计方式就不存在这方面的问题了。结构如下：

{"ads" :
　[
　 {"ad_placement_id": placementID,
　"ad_type": adType,
　"ad_data": adData},
　 ...
　]
}

在上面最后的实现中，所有的key都是const，即"ads", "ad_placement_id","ad_type"和"ad_data"，整个API都很容易扩展，保持良好的兼容性。

三. 别人总结的经验

网上也有一些经验总结，可以参考：

  1. HTTP API Design Guide （有中文翻译）
  2. Best Practices for Designing a Pragmatic RESTful API
  3. API Design Principles （QT的API设计原则--Restful API和Lib API大同小异）
  4. 虚拟研讨会：如何设计好的RESTful API？（InfoQ的一个总结）
上一篇下一篇

猜你喜欢

热点阅读