restful api接口设计风格以及思路

以一个开发者的角度来看,我们没有必要把rest这种思想跟理念搞得特别清楚,我们只需要大概知道它的规范即可,在工作中能够让接口规范起来,就达到目的了。

restful 可以理解为是rest思想风格的实现

既然是在开发API接口,从正常角度分析来看,得有一套规范吧,就像框架一样会有条条框框

个人认为,实现resftul api接口的规范做到几下几点就算是不错了

1、规范URL

在设计API时,URL是资源的来源,也是API的源。

设置一个规范合理,符合restful风格的API是什么样的呢?它没有样子,只有思想

首先,要遵循动宾结构。

动词即为HTTP协议的请求方法,如:

GET 获取 \POST 新建\PUT 更新\DELETE 删除等(建议大写)

宾语,即可选名词,名词有单数和复数,规范建议用复数 

例子:获取所有订单

以前的API:https://xxx.com/getorders      (method: get)

restful api:https://xxx.com/orders?all=true (method: get)

上面前者的扩展性不够强,并且没有名词,不符合restful规范

后者用了orders名词复数,并且语义上很通俗易懂的告诉了客户端人员all=true,这是要拿所有的订单

如果要扩展,可以变换参数

2、状态码

HTTP1.0协议有很多状态码,在restful中,3开头的状态码是用不到了。

对于状态码,restful规范起来的话,那就是:

一、明确状态码的意思,并且让客户端人员清楚知道

二、要根据不同的请求方法规定不同的状态码(例:GET方法,成功返回应该是状态码:200,POST方法作为更新成功状态码:201,DELETE方法删除资源状态码:204)

三、值得一提是401与403状态码,401是未经过授权的用户被拒绝访问,403是授权用户信息出现错误被拒绝访问

3、错误码

其实很多地方都可以看到类似这种规范的做法

开发过小程序或者公众号的人都知道,调用微信服务器代码出现错误时会有一串错误码,带着错误码到官方文档中就可以找到对应的错误信息,这是一种规范

而这个错误码的定义呢可以是任意的,你随意就好

个人建议,在服务器端应该有个文本文件是来存储错误码的,这样的好处是:

一、方便于自己去查找相应的错误(因为接口一多,你自己也不记得了)

二、方便提供给客户端人员查看错误信息

4、服务器错误处理

关于服务器错误处理,个人认为可以从两方面考虑:

一、是真的不知道哪里出错了,服务器自己报的错误,这时候我们给前端提示的应该是状态码500

二、是我们后端接口有问题,但跟客户端人员没有任何关系 的情况下,这时候状态码也应该是500

当出现500状态码的时候,一定要record日志,这也是非常重要的

最后提两点:

一、千万不要用200状态码来返回错误信息,这是非常不规范的操作,是什么错误就返回合适的状态码,错误一般情况下是401状态码,将错误信息放到请求体中

二、看似比较完整的restful api还差最后一步,你在设计完所有的接口之后,应该有一个公共查看URL的地方,一般建议是给一个JSON文件让客户端人员去查看,也便于后期公开化(如果你的平台够牛的话),当然你不对外的话,也可以这么做,很多开发者,包括我自己都会选择用第三方的接口文档工具来写接口信息,为了更贴近restful api风格,建议加上

发布了45 篇原创文章 · 获赞 7 · 访问量 1万+

猜你喜欢

转载自blog.csdn.net/qq_36431166/article/details/101012221