SpringMVC05 RESTful风格

1、RESTful 是什么
RESTful 是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

2、传统方式操作资源

• 查询（GET）http://127.0.0.1/item/queryUser?id=1
• 新增（POST）http://127.0.0.1/item/saveUser
• 更新（POST）http://127.0.0.1/item/updateUser
• 删除（GET或POST）http://127.0.0.1/item/deleteUser?id=1

3、RESTful 的请求方式
可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中，GET 用于查询资源，POST 用于创建资源，PUT 用于更新服务端的资源的全部信息，PATCH 用于更新服务端的资源的部分信息，DELETE 用于删除服务端的资源。

public enum RequestMethod {
	GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE
}

4、RESTful 操作资源

• 查询列表（GET）http://127.0.0.1/item/users
• 查询单个用户（GET） http://127.0.0.1/item/users/1
• 新增用户（POST） http://127.0.0.1/item/users
• 更新某个用户信息（部分字段更新）（PATCH）http://127.0.0.1/item/users/1
• 更新某个用户信息（全部字段更新）（PUT）http://127.0.0.1/item/users/1
• 删除某个用户信息（DELETE）http://127.0.0.1/item/users/1

5、RESTful 好处
让url 不暴露具体字段信息，安全；还有不需要去用动作描述接口名，直接用请求方式就可以了，还可以复用url

6、API设计风格基本规则

• 使用名词而不是动词

不要使用：/getAllUsers；/createNewUser；/deleteAllUser；restful 风格可以帮助避免这一点。

• Get方法和查询参数不应该改变资源状态

使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态，不要使用GET 进行状态改变

• 使用复数名词

/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting

• 使用子资源表达关系

GET /cars/711/drivers/       // 返回 car 711的所有司机
GET /cars/711/drivers/4      // 返回 car 711的4号司机

• 使用HTTP头决定序列化格式

在客户端和服务端都需要知道使用什么格式来进行通信，这个格式应该在HTTP头中指定:
Content-Type：定义请求的格式；
Accept ：定义允许的响应格式的列表

• 使用Http状态码处理错误

如果你的API没有错误处理是很难的，只是返回500和出错堆栈不一定有用

Http状态码提供70个出错，我们只要使用10个左右：

200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长

304 – Not Modified – 客户端使用缓存数据

400 – Bad Request – 请求无效，需要附加细节解释如 "JSON无效"
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。

500 – Internal Server Error – API开发者应该避免这种错误。

使用详细的错误包装错误：

{

  "errors": [

   {

    "userMessage": "Sorry, the requested resource does not exist",

    "internalMessage": "No car found in the database",

    "code": 34,

    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"

   }

  ]

}