RESTful
1、前言
RESTful 架构，就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。
但是，到底什么是 RESTful 架构，并不是一个容易说清楚的问题。下面，我就谈谈我理解的 RESTful 架构。、
RESTful 它不是一个具体的架构，不是一个软件，不是一个框架，而是一种规范。在移动互联网兴起之前，我们都很少提及 RESTful，主要是因为用的少，移动互联网兴起后，RESTful 得到了非常广泛的应用，因为在移动互联网兴起之后，我们再开发后端应用，就不仅仅只是开发一个网站了，还对应了多个前端（Android、iOS、HTML5 等等），这个时候，我们在设计后端接口是，就需要考虑接口的形式，格式，参数的传递等等诸多问题了。
2、RESTful的来源
REST：Representational State Transfer（表象层状态转变），如果没听说过REST，你一定以为是rest这个单词，刚开始我也是这样认为的，后来发现是这三个单词的缩写，即使知道了这三个单词理解起来仍然非常晦涩难懂。如何理解RESTful架构，最好的办法就是深刻理解消化Representational State Transfer这三个单词到底意味着什么。
1.每一个URI代表一种资源；
2.客户端和服务器之间，传递这种资源的某种表现层；
3.客户端通过四个HTTP动词（get、post、put、delete），对服务器端资源进行操作，实现”表现层状态转化”。
rest是一种架构风格，跟编程语言无关，跟平台无关，采用HTTP做传输协议，根据rest原则所理解，网络上任何一个资源就是一个实体，比如网上的一张图片，一首歌，一个服务等等，这些实体都可以通过URI（统一资源标识符）来定位。如果一个架构符合REST原则，就称它为RESTful架构
3、RESTful7大原则
（1）、C-S架构
数据的存储在Server端，Client端只需使用就行。两端彻底分离的好处使client端代码的可移植性变强，Server端的拓展性变强。两端单独开发，互不干扰。
（2）、无状态
http请求本身就是无状态的，基于C-S架构，客户端的每一次请求带有充分的信息能够让服务端识别。请求所需的一些信息都包含在URL的查询参数、header、body，服务端能够根据请求的各种参数，无需保存客户端的状态，将响应正确返回给客户端。无状态的特征大大提高的服务端的健壮性和可拓展性。
（3）、统一的接口
这个才是REST架构的核心，统一的接口对于RESTful服务非常重要。客户端只需要关注实现接口就可以，接口的可读性加强，使用人员方便调用。
（4）、一致的数据格式
服务端返回的数据格式要么是XML，要么是Json（获取数据），或者直接返回状态码，有兴趣的可以看看博客园的开放平台的操作数据的api，post、put、patch都是返回的一个状态码 。
自我描述的信息，每项数据应该是可以自我描述的，方便代码去处理和解析其中的内容。比如通过HTTP返回的数据里面有 [MIME type ]信息，我们从MIME type里面可以知道数据的具体格式，是图片，视频还是JSON，客户端通过body内容、查询串参数、请求头和URI（资源名称）来传送状态。服务端通过body内容，响应码和响应头传送状态给客户端。这项技术被称为超媒体（或超文本链接）。
除了上述内容外，HATEOS也意味着，必要的时候链接也可被包含在返回的body（或头部）中，以提供URI来检索对象本身或关联对象。下文将对此进行更详细的阐述。
如请求一条微博信息，服务端响应信息应该包含这条微博相关的其他URL，客户端可以进一步利用这些URL发起请求获取感兴趣的信息，再如分页可以从第一页的返回数据中获取下一页的URT也是基于这个原理。
（5）、系统分层
客户端通常无法表明自己是直接还是间接与端服务器进行连接，分层时同样要考虑安全策略。
（6）、可缓存
在万维网上，客户端可以缓存页面的响应内容。因此响应都应隐式或显式的定义为可缓存的，若不可缓存则要避免客户端在多次请求后用旧数据或脏数据来响应。管理得当的缓存会部分地或完全地除去客户端和服务端之间的交互，进一步改善性能和延展性。
（7）、按需编码、可定制代码（可选）
服务端可选择临时给客户端下发一些功能代码让客户端来执行，从而定制和扩展客户端的某些功能。比如服务端可以返回一些 Javascript 代码让客户端执行，去实现某些特定的功能。
提示：REST架构中的设计准则中，只有按需编码为可选项。如果某个服务违反了其他任意一项准则，严格意思上不能称之为RESTful风格。
4、RESTful最佳实践
（1）、版本
如github开放平台
https://developer.github.com/v3/
就是将版本放在url，简洁明了，这个只有用了才知道，一般的项目加版本v1，v2，v3?好吧，这个加版本估计只有大公司大项目才会去使用，说出来不怕尴尬，我真没用过。有的会将版本号放在header里面，但是不如url直接了当。
https://example.com/api/v1/
（2）、参数命名规范
query parameter可以采用驼峰命名法，也可以采用下划线命名的方式，推荐采用下划线命名的方式，据说后者比前者的识别度要高，可能是用的人多了吧，因人而异，因团队规范而异吧。
https://example.com/api/users/today_login 获取今天登陆的用户
https://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列
（3）、url命名规范
API 命名应该采用约定俗成的方式，保持简洁明了。在RESTful架构中，每个url代表一种资源所以url中不能有动词，只能有名词，并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可
规范后的RESTful风格的url，形式固定，可读性强，根据users名词和http动词就可以操作这些资源
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）、统一返回数据格式
- code——包含一个整数类型的HTTP响应状态码。
- status——包含文本：”success”，”fail”或”error”。HTTP状态响应码在500-599之间为”fail”，在400-499之间为”error”，其它均为”success”（例如：响应状态码为1XX、2XX和3XX）。这个根据实际情况其实是可要可不要的。
- message——当状态值为”fail”和”error”时有效，用于显示错误信息。参照国际化（il8n）标准，它可以包含信息号或者编码，可以只包含其中一个，或者同时包含并用分隔符隔开。
- data——包含响应的body。当状态值为”fail”或”error”时，data仅包含错误原因或异常名称、或者null也是可以的
返回成功的响应json格式：
{
"code": 200,
"message": "success",
"data": {
"userName": "123456",
"age": 16,
"address": "beijing"
}
}
返回失败的响应json格式：
{
"code": 401,
"message": "error message",
"data": null
}
（5）、http状态码
在之前开发的xamarin android博客园客户端的时候，patch、delete、post操作时body响应里面没有任何信息，仅仅只有http status code。HTTP状态码本身就有足够的含义，根据http status code就可以知道删除、添加、修改等是否成功。(ps:有点linux设计的味道哦，没有返回消息就是最好的消息，表示已经成功了)服务段向用户返回这些状态码并不是一个强制性的约束。简单点说你可以指定这些状态，但是不是强制的。常用HTTP状态码对照表
HTTP状态码也是有规律的
- 1**请求未成功
- 2**请求成功、表示成功处理了请求的状态代码。
- 3**请求被重定向、表示要完成请求，需要进一步操作。 通常，这些状态代码用来重定向。
- 4** 请求错误这些状态代码表示请求可能出错，妨碍了服务器的处理。
- 5**（服务器错误）这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误，而不是请求出错。
5、SpringMVC 的支持
SpringMVC 对 RESTful 提供了非常全面的支持，主要有如下几个注解：
- @RestController
我们通常使用ajax+json实现restful架构风格，请求和响应的数据都使用json格式，那就需要在controller的每个方法上加上@ResponseBody来标注该方法返回值放到响应体中，这样就不太方便了，此时就可以使用@RestController注解来代替之前的@Controller注解，这样就标注了当前controller中的每个方法的返回值要放到响应体中，就不用在每个方法上写@ResponseBody注解了。 - @RequestBody
restful风格的请求数据是使用json格式，此时我们在要接收请求参数的javabean前面添加@RequestBody就可以将请求的数据赋值到相应的bean属性中。 - @GetMapping
该注解用来替代RequestMapping，特点是@GetMapping只处理get方式的请求。 - @PostMapping
该注解用来替代RequestMapping，特点是@PostMapping只处理post方式的请求。 - @PutMapping
该注解用来替代RequestMapping，特点是@PutMapping只处理put方式的请求。 - @DeleteMapping
该注解用来替代RequestMapping，特点是@DeleteMapping只处理delete方式的请求。 - 另外还有一个提取请求地址中的参数的注解 @PathVariable
详情参看文章：
https://blog.csdn.net/kebi007/article/details/102927209
http://www.monkey1024.com/framework/1322
http://springmvc.javaboy.org/2019/1117/restful
