即日起在codingBlog上分享您的技术经验即可获得积分,积分可兑换现金哦。

Restful API实践经验

编程语言 u010136832 35℃ 0评论
本文目录
[隐藏]

在我有限的经历当中我曾经写过很多的API,有的是给内部用的,有的作为商用,有的用C、C++,有的用python、go,但是

尽管我认为我在API设计上有很多经验,当我一段时间再次设计一系列的API的时候,还是会在开始给自己刨坑。

总结过去,面向未来!是时候整理一下API从设计到实现中的点点滴滴需要注意的事情。

1. 一、了解业务,让接口简单,压缩数量

    如果你只是简单的开发几个接口供别人使用其实大可不必需要在这方面做详细的考虑,但是如果作为一个项目的成员,你所开发的

API未来会正式的发布出去作为商用,可能无数的二次开发的用户会简介或者是直接的使用你提供的接口,这时候就需要仔细的考虑好

要提供哪些接口,而不是简单的对所有的功能点提供单一的配置的接口。

    对于大多数的数据库驱动型的系统来说,提供的最多的可能就是一些配置接口,我曾经写过的一套API,就是针对一个系统的所有的表,进行增删改查

但是大多数的业务系统,表与表之间或者是存储器与存储器之间还是存在一定的联系,有时候一个接口可以做到的事情,分开成两个或者三个接口做,

必然造成多余的连接请求。

2. 二、参数检查统一化

    入参检查可能是一个接口在序列化处理逻辑中首先第一步需要做的,错误的入参对后继的逻辑没有任何的意义,入参检查涉及方方面面:

参数类型,参数个数,参数之间相互依存关系、字符串参数长度范围、整型参数大小范围,是否允许为空,是否为必填参数等等,都需要进行检查

只有参数检查顺利通过,才有成功执行的可能。现实的情况是,不同的接口参数的上述属性可能全然不同,但是有些东西却可以抽离出来,比如字符串长度检查

依存关系检查,抽离出一个公共的function模块,这样减少了代码的冗余也方便维护与提升效率。

3. 三、状态码要设计好

   大多数的API接口都不是一个存在的,往往是一系列的接口,对于开发者来说,针对一个接口中的各种情况返回不同的状态码其实没有什么大不了的,只要在接口文档中

做详细的说明,使用者出现问题时根据文档便可以知道问题的原因,但是我还是建议在定义状态码的时候尽量让他们有规律可循,

我曾经在设计一个系统:

50开头——–参数错误

60开头——–数据库执行错误

70开头——-逻辑处理过程中错误

80开头——–异常

90开头——-其他

尽管我没有在接口文档中明确的说明这个规律,但是对于任何一个使用这套接口的用户来说,我敢说在调试阶段一定减少了他不少的工作量,因为

仅仅通过前两个数字就基本可以断定是哪个部分出的问题,当然具体锁定问题,也就节省了时间

4. 四、告诉别人为什么会出错

    我们可能都有过这样的经历,知道错,但是不知道自己为什么会错。接口也是一样,当你返回一个状态码为错误状态的时候,最好是说明,具体的或者是

可能的错误的原因。如果你只是简单的写出参数错误或者是长度不对,那就太不近人情了,具体哪个参数错误,长度不对,正确的长度是多少。对任何一个使用

这一套API的人来说,我想都会从心底里肯定你的做法。

5. 五、安全

5.1.     1、防请求风暴

              对于一般的商用的API来说,我们一般都会考虑自己的系统的吞吐量,但是不管我们怎样的设计或者是优化,可能都会承受不了别人的恶意的攻击,如果没有考虑这一点

          只要认证通过就直接逆来顺受的处理,而不顾及系统承受能力,导致的无非就是系统在某一时间的奔溃或者是导致通路阻塞,正常客户的请求得不到迅速的响应,影响

          产品的运营。

              提前定义好系统的最大的并发量可能是解决这一问题的一个方法,在任何的请求进来的时候,顺带检查当前的并发量,将多余的请求放置队列,一次处理,这种策略解决的是系统的

           稳定性,保证系统对所有的请求的响应速度。但是对正常用户的体验并不能保证。

             针对单个客户进行限制,创建空间保存一个客户的session和请求时间,规定两次请求之间的硬性间隔时间,结和系统的整体的并发量和CQS,保证对恶意重复请求进行屏蔽,处理正常

            用户的请求。  

5.2.     2、防SQL

            虽然现在很多的框架比如falsk,Django 这些能够实现API的框架都提供了防SQL注入的功能,但是有时不可避免的我们有些语言是没有这种类似的框架,就不得不考虑这个问题

5.3.  


6. 六、文档

       一套好的API,最重要的可能就是文档的编写,没有好的文档,即时接口编码在优秀,用户用不明白或者是出了问题找不到解决的方法或者是不知道错误的原因,都会严重的下拉整套服务

的质量。

       那么一份接口文档需要哪些元素呢?

       带链接的目录:之所以一定要带链接,是因为最直接的应用就是用户找到相应的接口希望可以直接链接过去一看究竟,虽然创建链接对于文档的编辑可能比较麻烦但是确实是点睛的作用。

        参数详细说明:一定要详细的说明,参数的类型、大小、长度、是否为NULL、是否必填等等


        使用实例:最好做个示范,你懂的,总有人会看不懂你在说什么,举个列子一切可能都解决了

        状态码:状态码是你必须要去解释的,因为这是结果,做一件事最重要的就是结果,你必须要让别人明白究竟结果是什么意义。

  常见的布局一:

常见的布局二:

7. 七、性能

    把性能放在最后说不是我的本意,我开发过一些软件系统,有时候最终困扰我们的就是功能实现后发现性能不是我们想要的,然后就是大刀阔斧的

修改和调整,其耗费的时间差不多是时间编码的时间的三分之一或者是更多,但是事实的情况是我们明明可以在开始的时候就做一些准备,或者这些问题就不会

发生或者不会那么严重。

涉及批处理:有些接口虽然简单但是涉及到的却是一个非常庞大的处理任务,最常见的就是数据库的批量的查询和修改或者是插入数据,如果你把这一切交给数据库

那么结果可能是未知的,或者好或者坏,但是不难预料的就是当处理的数量级很大时,无疑会处理很长时间。如果能在开始的时候就考虑到这点,你可能会加入分量处理

或者是交给多个数据库连接分开处理,或许都能避免。

    除了单个的接口可能面对的问题,系统的整体的任务分发也需要考虑进去,分布部署、多级任务分发等等。

转载请注明:CodingBlog » Restful API实践经验

喜欢 (0)or分享 (0)
发表我的评论
取消评论

*

表情