restful

01restful

RESTful只是一种架构方式的约束，给出一种约定的标准，全严格遵守RESTful标准并不是很多，也没有必要。但是在实际运用中，有RESTful标准可以参考，是十分有必要的。有一种约定大于配置的感觉。

02 RESTful的来源

如何理解RESTful架构，最好的办法就是深刻理解消化Representational State Transfer这三个单词到底意味着什么。

• 1.每一个URI代表一种资源；
• 2.客户端和服务器之间，传递这种资源的某种表现层；
• 3.客户端通过四个HTTP动词（get、post、put、delete），对服务器端资源进行操作，实现”表现层状态转化”。

03 RESTful6大原则

1. C-S架构

前后端开发的分离；好处使client端代码的可移植性变强，Server端的拓展性变强。两端单独开发，互不干扰。

2. 无状态

无连接状态的请求：http请求本身就是无状态的，客户端的每一次请求带有充分的信息能够让服务端识别。请求所需的一些信息都包含在URL的查询参数、header、body，服务端能够根据请求的各种参数，无需保存客户端的状态，将响应正确返回给客户端。

当然这总无状态性的约束也是有缺点的，客户端的每一次请求都必须带上相同重复的信息确定自己的身份和状态（这也是必须的），造成传输数据的冗余性。

3.统一的接口

服务端返回的数据格式XML，Json，或者状态码。

自我描述的信息，每项数据应该是可以自我描述的，方便代码去处理和解析其中的内容。比如通过HTTP返回的数据里面有 [MIME type ]信息，我们从MIME
type里面可以知道数据的具体格式，是图片，视频还是JSON，客户端通过body内容、查询串参数、请求头和URI（资源名称）来传送状态。服务端通过body内容，响应码和响应头传送状态给客户端。这项技术被称为超媒体（或超文本链接）。

4.系统分层

客户端直接或者是间接与端服务器进行连接，分层时同样要考虑安全策略。

5.可缓存
在万维网上，客户端可以缓存页面的响应内容。因此响应都应隐式或显式的定义为可缓存的，若不可缓存则要避免客户端在多次请求后用旧数据或脏数据来响应。(但是自己在开发项目过程中很少使用，只需要自己有cookie就行)

6.按需编码、可定制代码

服务端可选择临时给客户端下发一些功能代码让客户端来执行，从而定制和扩展客户端的某些功能。比如服务端可以返回一些 Javascript代码让客户端执行，去实现某些特定的功能。（一般来说，只有实现以上几点才能说是restful风格，但并非是完全做到）

03 RESTful的7个最佳实践

1. 版本

就是将版本号放在url，简洁明了，但是我经常放到readme。

2.参数命名规范

一般采用下划线命名的方式，驼峰命名也可以。

String login_name  //登陆人姓名

3.url命名规范

API 命名应该采用约定俗成的方式，保持简洁明了。在RESTful架构中，每个url代表一种资源所以url中不能有动词，只能有名词，并且名词中也应该使用复数。实现者应使用名词和相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可。

https://example.com/api/users GET 获取所有用户信息 
https://example.com/api/users/1 GET 获取标识为1用户信息 
https://example.com/api/users/1 DELETE 删除标识为1用户信息 
https://example.com/api/users/1 Patch 更新标识为1用户部分信息,包含在body中 
https://example.com/api/users POST 添加新的用户

4. 统一返回数据格式
以实际项目开发为例，json返回格式。

• code——包含一个整数类型的HTTP响应状态码。
• status——包含文本：”success”，”fail”或”error”。HTTP状态响应码在500-599之间为”fail”，在400-499之间为”error”，其它均为”success”。
• message——当状态值为”fail”和”error”时有效，用于显示错误信息。
• data——包含响应的body。当状态值为”fail”或”error”时，data仅包含错误原因或异常名称、或者null也是可以的

返回成功的响应json格式

{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "123456",
    "age": 16,
    "address": "beijing"
  }
}

5. http状态码
（状态码详细还会进行更新）

自己开发过程中还跟少用到，一般只有http status code code。HTTP状态码本身就有足够的含义，根据http status code就可以知道删除、添加、修改等是否成功。服务段向用户返回这些状态码并不是一个强制性的约束。常用HTTP状态码对照表，HTTP状态码也是有规律的

• 1**请求未成功
• 2**请求成功、表示成功处理了请求的状态代码。
• 3**请求被重定向、表示要完成请求，需要进一步操作。 通常，这些状态代码用来重定向。
• 4** 请求错误这些状态代码表示请求可能出错，妨碍了服务器的处理。
• 5**（服务器错误）这些状态代码表示服务器在尝试处理请求时发生内部错误。

6. 合理使用query parameter

在请求数据时，客户端经常会对数据进行过滤和分页等要求，而这些参数推荐采用HTTP Query Parameter的方式实现。

搜索用户，并按照注册时间升序、活跃度降序
https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc

7. 多表、多参数连接查询如何设计URL

自己在使用多参数查询时，会在后台服务器设置工具类，将参数值以对象的方式传到后台进行解析。