如何开发设计更加符合规范的API
其他
2018-05-20 22:11:17
阅读次数: 2
一、开发API需要考虑的几个问题
1、跨平台性
所谓跨平台是指我们的接口要能够支持不同的终端，比如android、ios、windowsphone以及桌面软件、网站等，一套接口，支持多端，“Write Once,Run Anywhere”。当然从本质上讲，服务器端的接口跟终端是没有太大关系的，但接口应该考虑到不同端的接入成本，应根据项目或公司自身情况应该做相应的版本处理。采用通用的解决方案，比如通信协议就采用最常用的HTTP协议，如果是即时通信，可以采用开放的XMPP协议，做游戏的可以采用可靠的TCP协议，除非TCP不够用了，再采用定制的UDP协议。数据交换采用xml或者json格式等等，因自己所处环境具体情况而定。总之，要达到的目标就是让不同的端能够很方便的使用你的接口。已知现实情况：
- 正规的API设计接口规范文档，已App界面为功能导向是设计移动端接口。意义：后端开发成本高，接口页面规范可查，App接入成本低，App维护性高。沟通成本低，对业务理解能力门槛低！
- 另类的设计，已后端业务为导向，提供大而全的API设计接口，以满足所有端的所有需求，接口传入各种各样的配置和参数,。意义： 后端开发成本低，App接入成本很高，App后期的维护性低，维护成本高，沟通成本高，对业务的理解能力门槛高！
2、客户端与服务端的肥瘦平衡
在以前C/S、B/S架构时，就已多次讨论过这个问题，客户端是瘦点好还是肥点好，当然也没有固定答案，需要自己根据实际情况去做权衡。客观原因，在移动APP开发中，由于客户端的修改会很费时费力，一是App应用需要经过各种渠道审核，耗费时间。更新修复问题的时间成本过高。另外，当前IOS开发人员、Android开发人员的人工成本普遍较高，人才紧缺，基于这两点，能在服务器端实现的功能就不要放在客户端，毕竟服务器端程序的修改要比客户端方便、灵活、快捷的多。作为项目负责人或技术负责人该站在什么角度去看这个问题？肥瘦平衡最终追求的是什么？。
3、考虑移动端的网络情况和耗电量
对于移动APP开发者来说， 网络流量和电池电量是不得不考虑的问题。不过，您也许会说，这些跟接口没啥关系吧，服务器端的接口还能管得了客户端的网络流量和电量？
- 对于网络情况，接口应该具备为不同的网络提供不同的内容的能力，通常，移动端的上网方式无非是2G（GSM、GPRS、EDGE）、3G（CDMA、TDSCDMA、WCDMA）、4G/5G、WIFI。设想一下，如果用户在流量需要花钱的情况下，你的app给用户展示了视频、音频、大量的图片和大量无用数据（接口中存在大量跟app页面无关的数据，俗称大而全的接口）。而没有通知用户的情况下用户会怎么想，毕竟国内的流量费用还是很贵的，应在不同的环境下提供不同的策略。
- 对于电量，app的哪些方面会消耗电量？比如app有大量的计算、有很炫的视觉画面都会消耗电量， 另外，不断的移动网络链接也会消耗大量的电量，我们都知道移动网络是通过无线电波来通讯的，那么发射装置就需要消耗一定的电量来发射和接收无线信号。特别的是，频繁的链接会不断的切换网络设备与移动基站之间连接状态，这都会消耗一部分电量。所以，对于接口而言，尽量用少的链接传输多的数据，和尽量少的数据接收交互。
4、接口需不需要要为移动客户端考虑，做相应的API适配
一种声音是不需要，后端写一套接口，不管是web端,Android,ios,wap等都调用相同的接口，后端维护简单。另一种声音是需要，要依据不同场景，开发相应的API接口（如移动端，web端等）。
相对于我目前而言第二种较为合理。提供一下例证，欢迎探讨。接口不仅仅是提供数据和功能就完事了，更应该充分考虑移动端的特性，为移动端提供更加方便、快捷的接口。比如，在移动端里，下拉刷新和上拉加载更多是很常见的功能，如果接口仍然按照传统的web思路，只提供按页读取的话，就会造成移动端的额外的数据请求和计算。这时，接口就应该针对这两种类型的操作提供额外的支持。再比如，对于一个新闻阅读类的app来说，最新的新闻列表里的文章，特别是前几条，用户很容易点击进去看，而后面的老的文章列表，一来用户下滑加载好几页的情况较少，二来过时的新闻用户也很少点。如果，接口在返回新闻列表时，对于最新的列表，可以直接把文章的正文（或者部分正文，比如一屏的内容）信息一起传给客户端，这样，用户在打开新闻详情页的时候，就不用再从服务器端获取了，自然可以做到秒开。当然，客户端要跟接口做好配合，搭配好，才能最大化的提高性能。比如，移动端都有左右滑动来看上一篇、下一篇文章或者图片的功能，如果，当用户请求某篇文章的时候，服务器端顺便也把下一篇文章的内容返回回来了，那么当用户看下一篇的时候，是不是就很快了呢。当然这种preload的方案也不能滥用，如果预加载数据的命中率较低的话，也不行，白白浪费了很多的流量。
二、API接口设计构思应该思考的问题
1、实用性
编写接口API应遵循实用性原则。
- 数据格式：推荐使用JSON格式数据，因为JSON有较好的跨平台性，以及数据格式占用字节数较少，当然也可采用XML、TEXT作为程序开发辅助。
- 如：服务器返回json数据结构一般为：
-
{
code：200
message: “success”
data: {
key1: value1,
key2: value2,
…
}
} code: 状态码，200表示成功，非200表示各种不同的错误
message: 描述信息，成功时为”success”，错误时则是错误信息
data: 成功时返回的数据，类型为对象、或数组... , 因此，data必须返回相应经过初始化的格式，数组如：[],对象：{}的格式，如果传入一个null,如果对象类型变成了String类型，那么肯定是报错的。
- 接口执行效率（接口访问速度）：APP有别于WEB服务，对服务器端要求是比较严格的，在移动端有限的带宽条件下，要求接口响应速度要快，对数据要求也比较严格，app需要什么数据就传什么数据，不可多传，过多的数据量影响处理速度，最重要的是影响传输效率和浪费用户流量。接口要规范，以面向对象的思想设计接口。
- API缓存：对APP运行的体验和流畅性来说，适当的缓存比较重要，不管是文件缓存还是memcache缓存，能让用户感知不知不觉中对App产生好的体验。
2、易用性
1)、接口、参数命名准确：无论是接口还是参数，命名都应该有意义，让人一目了然。（接口推荐根据APP效果图栏目进行命名）
2)、一个页面尽可能就用一个接口： 现在很多的APP页面都有广告、焦点图、文章列表等，对于这些不同格式的数据，不可能都分配一个接口，这样加大了APP请求接口数，影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端，或把相似的部分功能合并已达到想要的效果，尽量不要出现一个页面七八上十个接口的情况。
3)、接口数据、状态：接口必须提供明确的数据状态信息，不管是成功的，还是失败的，都必须返回给APP客户端，系统级异常，业务级异常，参数及异常都应有所体现。否则，接口的协议失去了所有的意义
4)、接口要有可扩展性：方便后期功能性调整，接口应具备可扩展性，但扩展性也不能盲目不切实际的幻想可能会出现不同的数据逻辑。
1)、接口安全：目前一般都是在APP客户端和服务器通过约定的算法，对传递的参数值进行验证匹配。但是如果APP程序被反编译，这些约定的算法就会暴露，特别是在安卓APP中，有了算法，完全就可以通过验证模拟接口请求。或者引入jwt令牌（token）等解决方案。
2)、加密规范：在传递用户名密码时，应采用规范的加密算法如MD5、RSA、DES，进行数据通信请求。
3)、https协议 ：对于敏感的api接口，使用https协议 ，也是一种不错的选择，这也是一个趋势。https是在http超文本传输协议加入SSL层，它在网络间通信是加密的，所以需要加密证书。https协议需要ca证书，一般需要相应的费用成本。
4、版本兼容性
接口不可能永远不变，它会随着需求的变化而做出相应的变动。接口的变化一般会有几种：
1)、数据的变化，比如增加了旧版本不支持的数据类型
2)、参数的变化，比如新增了参数
3)、接口的废弃，不再使用该接口了
为了适应这些变化，必须得做接口版本的设计。实现上，一般有两种做法：1、每个接口有各自的版本，一般为接口添加个version的参数。2、整个接口系统有统一的版本，一般在URL中添加版本号，比如http://api.demo.com/v2。
大部分情况下会采用第一种方式，当某一个接口有变动时，在这个接口上叠加版本号，并兼容旧版本。App的新版本开发传参时则将传入新版本的version。如果整个接口系统的根基都发生变动的话，比如微博API，从OAuth1.0升级到OAuth2.0，整个API都进行了升级，那同样API必须做相应变化。有时候，一个接口的变动还会影响到其他接口，变动时需先想梳理清楚可能会涉及的接口。在做相应的变更处理。
总之根据自身业务需求针对性的开发与用户习惯相应的页面设计和App接口方案才是最理想的考虑方式方法。
转载自blog.csdn.net/zhihua_w/article/details/79246769