总结常见的违背Rest原则的接口设计作法

此文已由做者郑华斌受权网易云社区发布。

REST这词咱们经常挂在嘴边，好比“开发一个rest接口”，又好比Spring项目的代码：

@RestControllerpublic class CommonController { @RequestMapping("/") public String index() { return "Welcome to Yanxuan DMS!";

}

CommonController使用了@RestController注解，顾名思义，告诉读者这是一个Rest接口的实现。然而以@RestController注解的接口却不必定符合Rest原则。结合最近的项目，总结下常见的违背Rest设计的一些作法。

1、一概使用POST或者GET方法
典型的错误作法：不管什么请求，一概用POST，或者‘增删改’用POST，‘查’用GET。

其实REST有个原则叫统一接口（uniform interface），统一接口原则建议了各http方法的使用场合，

GET：获取资源，返回消息头和消息表示，即header和body。

HEAD：获取资源元数据，返回消息头

DELETE：删除资源

POST：REST设计中，POST一般用来为一个已有资源建立一个从属资源（subordinate resource），如AWS S3的POST Object(或者称web post)接口。

PUT：建立或修改一个资源

PUT和POST的区别比较微妙，这里拿AWS S3（或者参考网易对象存储NOS）的接口设计来举例。其中AWS S3的详细API文档参见：http://docs.aws.amazon.com/Am...。 S3有两种资源，桶（bucket）和对象（object），对象从属于某个桶。

建立一个桶的接口为：

PUT /BucketName HTTP/1.1
Host: s3.amazonaws.com
建立/修改一个对象的PUT Object接口为：

PUT /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com[对象数据]
AWS S3同时提供了POST Object接口，一样能够建立/修改一个对象，以下

POST /BucketName HTTP/1.1Host: s3.amazonaws.comContent-Type: multipart/form-data; boundary=9431149156168[包含对象数据的body]
获取对象的GET Object接口为：

GET /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com
一样的建立/修改一个对象，一个用PUT方法，另外一个用POST方法，为何？关键在于URL，PUT请求的目标URL（这里为/BucketName/ObjectName），就是未来用于获取该对象的URL，即PUT Object和GET Object的URL是一致的。可是POST Object的URL与GET ObjectURL不同，POST 请求只知道父资源的URL（即/BucketName），表示在该父资源下建立新资源，至于新资源的确切URL，是由服务器决定的，通常来讲是POST请求的响应应该包含一个Location消息头，其包含新建从属资源的URL。

安全性safe和幂等性idempotent

REST设计还应该遵循安全性和幂等性约束，以下：

GET和HEAD应当是安全的：GET和HEAD请求不该该致使服务器状态发生改变

GET、HEAD、PUT和DELETE应当是幂等的：向一个URL发送屡次PUT和DELETE请求，跟只作过一次请求同样。好比PUT不能是append语义，不然不幂等。GET和HEAD也是幂等。

统一接口原则的好处：

给一个资源URI，不用看文档就知道能够有GET、DELETE等操做及其意义，世界通用。

安全性和幂等性增长了http的可靠性：若是请求没成功（但也许已成功了），只需从新发一次便可，不用担忧反作用。

2、HTTP Code一概返回200
典型的错误作法：不管成功失败，HTTP Code一概返回200，具体错误信息交由json body里的内容来判断，举例以下，

某甲服务xxx接口的响应以下

HTTP/1.1 200 OK{ "status":1, //1: 成功 0: 参数异常 -1: 失败

"message":"" //返回的消息
成功时返回的数据

}
某乙服务xxx接口的响应以下

HTTP/1.1 200 OK{ "code":200, //1: 成功 0: 参数异常 -1: 失败

"msg":"" //code非200时返回的错误信息
"data":{成功时返回的数据内容}

}
其实RESTful的设计的一个标志特征是充分并正确利用HTTP响应码，典型的如：

200 -- OK，成功

301 -- Moved Permanently，重定向

400 -- Bad Request，错误的请求，好比缺乏参数或者参数值不对

403 -- Forbidden，无权限访问

404 -- Not Found，url不存在

500 -- Internal Server Error，系统错误，如数据库访问失败或者bug致使的错误

设计REST接口应该遵循上面的响应码，语义明确并通用。若是像上面例子那样，任何状况都一概返回200，而具体成功与否须要到http响应消息体里去解析，并且不一样的服务或开发者自定义消息体的格式，那么服务调用方就须要针对不一样的服务写不一样的判断逻辑，增长系统交互复杂性。

有些通用的客户端，会针对301自动处理重定向，针对500以上的响应自动重试，而一概返回200的设计是无法使用这些特性的，只能调用方一一自个处理。

3、 面向操做而不是面向资源的url设计
典型的错误作法：设计的URI是面向操做而不是面向资源的，举例以下，

某系统 设计的渠道相关的URI是这样的：

新增渠道

POST /xhr/thirdparty/admin/channel/add.json?{渠道信息参数}
编辑渠道

POST /xhr/thirdparty/admin/channel/update.json?{渠道信息参数}
删除渠道

POST /xhr/thirdparty/admin/channel/delete.json?channelId=id
这里的接口设计有三个特色：

http方法都是POST；

URI里携带操做信息，如URI里出现“add”，“update”，“delete”等字眼；

同一个资源因为操做不同而URI不同。

其实REST式的设计中，URI便是资源的名称，也是资源的地址，由于不一样的操做而资源地址不同是不合适的。资源的操做（方法信息）应该由统一接口来表示，即http 方法PUT、POST、GET、DELETE等，而不该该放到URI中。

对照统一接口和面向资源这两个特征来设计，上面的接口RESTful化能够是这样的：

新增渠道

POST /xhr/thirdparty/admin/channel

[渠道具体信息]
修改渠道

PUT /xhr/thirdparty/admin/channel?channelId=id 或者PUT /xhr/thirdparty/admin/channel/${id}

[渠道具体信息]
删除渠道

DELETE /xhr/thirdparty/admin/channel?channelId=id或者DELETE /xhr/thirdparty/admin/channel/${id}
渠道的地址为/xhr/thirdparty/admin/channel?channelId=id或者/xhr/thirdparty/admin/channel/${id}，重在url惟一。

参考文献
《RESTful Web Services》

文章来源： 网易云社区