API接口设计要考虑的几个重要原则和方法总结

1.合理的接口命名；

接口的命名必须规范优雅，在未看到接口文档时，就可以根据接口的URL明白接口的功能是什么？
2.入参和出参的规范化定义，有统一的风格；

一个项目内的所有接口，必须有统一的风格，统一返回格式，约定业务层错误编码，每个编码可以携带明确的错误信息。出入参字段含义明确，采用统一的命名规范，如驼峰命名等。返回格式统一采用json格式。举一个例子：

{
"status": "failure",
"error_code": 100003,
"error_message": "未获取到用户信息",
"data":
}


status标识接口是否逻辑处理成功；error_code为不同类型错误信息对应的唯一错误码，error_message为错误信息的简要描述信息（注意某些数据或者信息是否可直接展示给用户），data则为需要返回给调用方的数据信息。

另外，每个参数一定要有明确且固定的数据格式，int就是int，string就是string，array就是array，object就是object，因为对于一些对数据类型要求比较严格的使用方，不明确的数据格式返回，可能会造成不可预知的错误。

下面给大家列一下Json里的六种基本数据格式：

Number：整数或浮点数
String：字符串
Boolean：true 或 false
Array：数组包含在方括号中
Object：对象包含在大括号{}中
Null：空类型


3.接口的功能定义要具备单一性；
单一性是指接口要做的事情应该是一个比较单一的事情，比如登陆接口，登陆完成应该只是返回登陆成功以后一些用户信息如uid即可，但很多人为了减少接口交互，返回一大堆额外的数据。

但有时候对于一些内部系统接口来讲，为了实现通用性，可能会提供一些通用的查询接口，即在同一个接口内返回尽可能多的信息，但也不建议这么做，至少不是一个好的实践

4.明确接口支持的协议；
接口要明确所支持的协议，是POST/GET/PUT/DELETE等的哪一个。一般来讲，同一个接口而言，尽量只支持一种协议，并且在接口被调用时，如果参数传递非接口定义协议，要明确提示返回错误信息，这样可以减少很多类似于“为啥我调接口参数都对还调不通”的问题的沟通成本。同时，严格的协议规范也可以避免一些意料之外的问题出现。例如：
您请求的资源不支持 http 方法“POST

5.是否支持幂等；
这是作为一个接口而言，很需要明确的一点，尤其是在一些特殊的应用场景下，是否支持幂等是需要首先明确的。比如下面这个例子：

发放卡券的接口：/coupon/card/handOut.json POST

这是一个卡券系统里发放租金卡的接口，支持POST协议传参。由于很多种原因，同一类卡券被某个人领取时，都可能会产生接口被调用不支持一次的情形，比如网络抖动、用户快速点击、甚至是恶意刷接口等，我们希望，对于“同一个调用”，我们给用户返回的结果应该是一致的，这就是幂等。实现幂等的方式有几种，比如卡券系统就是通过生成订单号的形式完成的接口幂等；

6、充分考虑接口的可扩展性，避免做大而全的接口；
要根据实际业务场景定义接口，充分考虑接口的可扩展性。比如自如的APP首页数据接口，我们可以设计成整个首页就一个大接口，但是假如这样，未来再次改版APP，我们可能就需要完全重新写这个接口，但假如我们按模块区分接口，可能我们仅需要开发新增加的模块的接口，对于以前有的，在数据结构不调整只做样式改变的需求里，就可以减少工作量的开发。
另外这么做还有一个优点，尤其对移动端作用尤为突出，由于移动端对带宽有限，所以，接口中尽量不要返回无用的信息，只返回真正需要的数据，进而减少由于过多的数据量影响处理速度，最重要的是影响传输效率。

7、接口里尽量不做客户端可以处理的逻辑，减少服务端压力；
接口主要是提供给客户端数据的，对于能够在客端完成的逻辑处理，尽量由客端来处理（当然APP比较特殊，如果改动这部分逻辑需要发版，还是需要放在后端），进而减轻后端服务器的压力，让后端接口更加“专心”做好数据服务；

8、清晰的日志分类、记录以及归档规范；
接口日志很重要，无论对于追溯问题还是解决bug，都有着举足轻重的作用。所以，好的日志规范，是一个很好的习惯。日志主要有info和error两种（warning一般不做记录，或者很少用到），info日志一般用于记录现场，用来追溯问题；error日志一般用于协作我们查找bug，定位代码问题。

另外日志也需要定期做归档处理，防止机器磁盘被日志文件大量占用。

更高级的，可以接入一些日志搜集和分析工具，如ELK等，将日志信息持久化存储以及可视化展示，更加方便的对日志信息进行使用。

9、版本控制：
这一点，对于接口来讲，非常重要。在实际的场景中，维护多个版本是非常常见的事情，在系统的迭代升级过程中，无可避免的会增减返回参数及入参，修改返回数据的结构，甚至会废弃原有接口改为新的数据接口。所以，为了不影响老版本应用的正常使用，大部分应用后台都会针对性的维护多个接口版本。
一般来讲，有2中常用的方式：
1.每个接口有各自的版本，一般为接口添加个version的参数。
2.整个接口系统有统一的版本，一般在URL中添加版本号，比如 http://api.zkbhj.com/v2。

【性能和高可用】

1、接口的平均响应时长、支持的并发数、TPS；
这个很重要，无论是我们自己设计的接口，还是我们在使用第三方提供的接口时，我们都需要明确接口的平均响应时长，因为这直接关系到你系统的安全性问题！如果在接口调用时，没有设置合理的超时时间甚至都没有设置超时时间，那么一旦所以依赖的接口出现问题甚至服务不可用时，对你调用方系统来讲，将是致命的，雪崩式的系统崩溃，很大一部分就是由于这个原因造成的。所以为了不害人害己，设计以及最终提供的接口，一定要提供一个明确的接口平均响应时长，而且要在接口文档中写明并强烈建议接口调用方设置合理的超时时间，防止由于接口超时而造成雪崩式的连锁反应。

2、数据库和缓存的选择；
为了提高接口性能，合理的选择数据库和缓存很是总要。一般情况下，关系型存储我们一般都会选择MySQL数据库，缓存一般都选择Redis。当然，MySQL数据库的分库分表，加索引用事务、读写分离等，redis作为缓存使用时的缓存时长、缓存数据类型等，都有他们的使用原则和最佳实践，这里不做赘述。我们这里只讨论在何种场景下要使用缓存。比如查询类型的接口，如果要查询的数据并不是实时性要求很高的接口，那我们可以进行缓存处理，比如APP首页接口，一般都是CMS里面配置的一些图文信息，我们有必要做缓存处理。当然可能里面有一部分数据是需要实时的，比如自如寓的管家信息，那我们可以把这一部分内容做实时的处理。

3、限流、熔断和降级；
对于一些特殊的应用场景，比如抢红包、秒杀等，要对接口进行限流处理，方式短时间内的高并发请求将接口搞死；

接口熔断和降级，是为了解决系统不被拖死，不影响核心业务流程而采取的措施，比如获取用户信息列表，实时获取用户头像和昵称的接口暂时不可用（比如根据设置，10个请求里6个以上都超时，则判定为服务不可用，触发熔断机制），我们可以主动放弃调用（熔断），只返回核心数据uid等，昵称和头像暂时返回默认数据（降级）；

4、消除单点，负载均衡；
对于任何一个接口服务，我们至少要有2台机器对外提供服务，禁止单点服务，单点一旦出问题，会直接造成服务不可用；

对于访问量很大的API服务，为了提供更加快速的接口响应，我们往往不是单台机器提供服务，而是有多台机器组成一个分布式集群对外提供服务。这个时候就会涉及到负载均衡，比如我们就会由nginx来做负载均衡，根据一定的策略机制，将接口请求平均的分发到不同的应用机器上进行处理和响应。进而提高接口的性能。

5、是否有第三方服务接口？
如果接口依赖了第三方服务接口，能用缓存就用缓存。这样可以进一步降低由于第三方接口不稳定给我们自己系统造成的波动。当然，也有一些第三方接口无法做缓存，比如就是要实时进行身份验证等，这个时候，超时时间的设置就尤为重要！

6、能异步处理的异步处理：
其实有很多场景下，一个接口里面的很多逻辑是可以异步处理的。举个例子：

比如用户注册场景，用户注册成功之后会给客户的邮箱发送一封激活邮件。常规的逻辑流程应该是，前段提交用户信息到注册接口，注册接口做各种校验，校验通过后，发送邮件，发送成功后，返回给前端告诉用户注册成功，请进入邮箱激活账号。其实，这个流程里的“发送邮件”就是可以拿出来异步处理的部分，当校验通过而且注册完成之后，我们把发送邮件这件事抛出去，交给另外一个就负责发邮件的任务进行处理（如我们现在有的补偿队列，或者是发一个MQ消息），然后直接返回给用户注册成功。这样，注册接口的平均响应时间一定会比第一种方案提高很多。

7、更高要求的高可用，可以采用异地机房部署；
在物理地域上就分开部署，两地同时崩溃的概率还是比较低的；

8、监控和报警；
在对接口建立高效的监控和报警机制，能够及时发现问题并通知到相应的人员进行第一时间的处理和跟进。

【稳定和安全】

1、身份验证；
在一些接口场景中，是要依赖于用户身份的，比如通过token还实现用户身份的验证；

2、接口防抓取和串改数据；
防止数据被轻易抓取到，我们可以采用https作为接口的网络传输协议，进而保证数据包不被轻易的就抓取和分析。即使这种情况下，依然被抓取到，我们还可以对传输的数据进行我们自己的加密处理，比如用对称加密算法AES或者非对称加密算法RSA，亦或是我们系统内部自己商定好的加密算法，对数据进行加密处理，这样，即使抓取到数据包，也很难分析出数据的原始信息。

对于防止数据被串改，可以使用sign验签，进一步防止接口参数被串改的可能性。

3、防刷；
接口防刷会有一些策略，根据实际的应用场景进行选择，比如增加图形验证码、接入智能验证码、时间戳限制单位时间内的调用次数、ip限制等；

另外监控很重要，及时发现异常的调用，进行封禁处理；

**

【其他】

**
1、是否需要支持跨域；
这一点是针对于H5提供接口时需要考虑的，因为一般情况下，实际的应用和接口所在的域并不是同一个域，基于浏览器的安全策略，对于XHR请求来讲，是不允许进行跨域请求的，所以，一般提供给H5的接口要支持跨域请求。当然解决跨域的方法也不在本次讨论的范围之内，目前主流的方式就是在服务器配置的header头信息中增加两项参数。

2、基于H5提供接口的一些安全性问题；
比如常见的CSRF攻击，我们可以在接口里验证 HTTP Referer字段、x-requested-with字段、header中增加token等，从一定程度上提高被CSRF攻击的门槛。

3、在代码结构层面，尽量和其他部分分开；
API集中由同一个系统“模块”提供，尽量不要和页面等其他功能混合开发。例如下面的项目分层模式就是一个较好的实践方案：

即所有API接口均分布在api内部，不与pc（PC站页面）、mobile（M站页面）等混合在一起。

4、文档：
好的接口，还有一项优点，就是会有为之配套的接口文档。如果希望降低接口文档的维护成本等，也可以使用开源的第三方自动化接口文档工具，比如swagger等。