SpringMVC Restful API设计总结 及Springboot构建Restful API 示例Demo

一. 什么是Restful

    REST : 以消息为中心的表述性状态转移（Representation State Transfer），是另一种类型的远程过程调用（RPC）机制，并且是通过简单的Http Url来触发，但是相反的，REST 和 RPC 几乎没有关系，RPC面向的是服务，关注的是行为和工作,  而REST 面向的是 资源(要处理的数据)，强调的是描述应用程序的事物和名词。

    可能上面的描述太抽象，下面举个URL的例子

1. http://localhost:8080/delUser?id=x
2. http://localhost:8080/user/x
   

     这是 删除user id 为 x 的请求，可以看出第一个 删除 这个动作 是包含在 URL中的，而第二个 Rest api 是以Http为依托的，不采用这种风格的URL，还是还原URL的本质：Uniform Resource Locator: 统一资源定位符，所以Rest 和 URL宗旨一样，面向的是资源，而不是动作行为。而对 user 这个资源 做何种行为 是 Http 方法来定义的 get  post put ...

@RequestMapping(value = "/user", method = RequestMethod.GET)
    public User get(@RequestParam String id){
        return userService.findById(id);
    }

@requestMapping注解有method属性，在没有指定method的值时，默认映射所有http请求方法，如果仅想接收一种请求方法，需用method=RequestMethod.GET或其他 请求方法指定，如果提交表单时form标签中method的请求方法与requestMapping中指定的不同，则会报错。 当请求Url为 http://localhost:8080/user/x， Http请求方式为 get（用于获取服务器资源） 时，就可以定位到上面的方法，并返回 对应 id 的 user 对象。

下面我们具体说一下Restful API 中URL路径写法 与 Http请求方式的关系

二. RESTful API 的路径URL

    在REST 中，资源是通过URL进行识别和定位的，而且关注的核心是 资源 而不是 行为，所以网址中不能有动词，只能有名词,而且名词往往与数据库的实体名字对应，API中的名词应该也使用对应的复数；例如一个关于 User的API 的路径：

http://api.demo.com/users/id  //请求某个id的user
http://api.demo.com/users    //请求所有的user

    另外有些API 会有版本的区别，一般可以将版本信息也放入路径中，更加方便直观

http://api.demo.com/v2/users/id
http://api.demo.com/v2/users

三. RESTful 的行为--Http动词

      在REST 中会有行为，它们是通过Http方法来定义的，也就是常用的 GET POST PUT PATCH DELETE 以及其他的方法，这些方法通常会匹配如下的CRUD 动作：

Create： POST
Read： GET
Update:	PUT、PATCH
Delete:	DELETE

        常用的Http动词的含义：

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

    示例：

GET /users：列出所有用户
POST /users ： 新建一个用户
GET /users/ID： 的用户
PUT /users/ID：更新某个指定用户的信息（提供该用户的全部信息）
PATCH /users/ID：更新某个指定用户的信息（提供该用户的部分改动信息）
DELETE /users/ID：删除某个用户
GET /users/ID/works：列出某个指定用户的所有工作
DELETE /users/ID/works/ID：删除某个指定用户的指定工作

    简单对比分析：

GET：网页常用的URL都是GET请求，用于查询，但是GET中的URL有长度限制，而且一些参数也会暴露在URL中
POST:把数据都存放在body里面，这样即突破了长度的限制；又保证用户无法直接看到。在使用表单时，比较常用
PUT和PATCH的功能都可以代表更新，但略有不同，PUT大多时候表示更新该资源的全部信息，而PATCH则更新部分信息。
POST和PUT的区别容易被简单地误认为“POST表示创建资源，PUT表示更新资源”；而实际上，二者均可用于创建资源，更为本质的差别是在幂等性方面（HTTP方法的幂等性是指一次和多次请求某一个资源应该具有同样的副作用）
POST所对应的URI并非创建的资源本身，而是资源的接收者。两次相同的POST请求会在服务器端创建两份资源，它们具有不同的URI；所以，POST方法不具备幂等性。
而PUT所对应的URI是要创建或更新的资源本身，对同一URI进行多次PUT的副作用和一次PUT是相同的；因此，PUT方法具有幂等性。

四. RESTful 的过滤信息

    对于有些请求返回的数据量比较多，API应该提供参数对结果进行过滤，常见的分页、指定数量、排序等过滤操作。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

五. 常见的状态码及错误处理

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

在实际设计中忽略错误处理，和简单返回500调用堆栈都是非常不友好且无用的。而是要结合具体信息将错误信息返回给客户端

{
    "timestamp": "2018-04-26T02:31:46.309+0000",
    "status": 400,
    "error": "Bad Request",
    "message": "Failed to convert value of type 'java.lang.String' to required type 'int'; ,
    "path": "/account/lis"
}

可以参考一些企业是如何处理的 https://juejin.im/entry/583fe0b461ff4b006c1aa075

六. Springboot 构建一套 RESTful API Demo

github-springboot-demo: https://github.com/liuyuanju7/springbootStudy