RESTful简介和使用

概述

REST：英文representational state transfer直译为表现层状态转移，或者表述性状态转移；Rest是web服务的一种架构风格，一种设计风格，是一种思想；同时Rest不是针对某一种编程语言的。
一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。
RESTful是一种设计风格，用于构建可伸缩、可维护和可扩展的网络服务。在Java中，可以使用各种方式来实现RESTful风格的API。
RESTful的一些基本原则和相关概念：

1. 资源（Resources）：RESTful API将数据和功能封装为资源，每个资源都有一个唯一的标识符（URI）。例如，一个用户资源可以表示为/users/{id}。
2. HTTP方法（HTTP Methods）：HTTP方法用于定义对资源的操作，常用的有：
   ○ GET：获取资源的信息。
   ○ POST：创建新的资源。
   ○ PUT：更新现有资源。
   ○ DELETE：删除资源。
3. 状态码（Status Codes）：RESTful API使用HTTP状态码来表示请求的结果。例如，200表示成功，404表示资源不存在，500表示服务器错误等。
4. 媒体类型（Media Types）：RESTful API使用媒体类型来指定数据的格式，常用的有：
   ○ JSON（application/json）：用于传输结构化的数据。
   ○ XML（application/xml）：用于传输和存储数据。
   在Java中，可以使用多种框架和技术来构建RESTful API，例如：
5. JAX-RS（Java API for RESTful Web Services）：是Java EE的一部分，提供了一套标准的API和注解，用于构建RESTful风格的Web服务。常用的JAX-RS实现包括Jersey和RESTeasy。
6. Spring MVC：是Spring框架的一部分，可以使用注解方式来构建RESTful风格的Web服务。Spring Boot提供了自动配置和简化开发的特性，使得构建RESTful API更加方便。
   无论选择哪种方式，都需要定义API的URI、请求方法、响应状态码和返回数据格式等，以满足RESTful的设计原则和要求。同时，还可以通过使用过滤器、拦截器、异常处理等技术来增强API的功能和安全性。
   总之，Java提供了多种工具和框架来实现RESTful API，开发者可以根据项目需求和个人喜好选择合适的方式。

优点

通过 HTTP 动词指定了不同的 CRUD 操作，将接口 URL 简化为了同一个地址，仅需要改变 HTTP 动词即可实现不同的操作。
另一方面，相对于 SOAP/XML 形式的 RPC 服务，Restful API 采用 HTTP/JSON 的形式传递数据，降低了传输数据量，同时提高了数据解析的效率，单位时间内的负载能力会高于 SOAP WebService 服务。
以webService为例通俗解释。
非Rest设计，以往我们都会这么写：
http://localhost:8080/admin/getUser （查询用户）
http://localhost:8080/admin/addUser （新增用户）
http://localhost:8080/admin/updateUser （更新用户）
http://localhost:8080/admin/deleteUser （删除用户）
总结：以不同的URL（主要为使用动词）进行不同的操作。
Rest架构：
GET http://localhost:8080/admin/user （查询用户）
POST http://localhost:8080/admin/user （新增用户）
PUT http://localhost:8080/admin/user （更新用户）
DELETE http://localhost:8080/admin/user （删除用户）
总结：URL只指定资源，以HTTP方法动词进行不同的操作。用HTTP STATUS/CODE定义操作结果。
Restful：遵守了rest风格的web服务便可称为Restful。
为什么需要Restful？
URL具有很强可读性的，具有自描述性
规范化请求过程和返回结果
资源描述与视图的松耦合
可提供OpenAPI，便于第三方系统集成，提高互操作性
提供无状态的服务接口，降低复杂度，可提高应用的水平扩展性
/版本号/资源路径
/v1/tags/{tag_id}
/v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20]
1、版本号
命名版本号可以解决版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留旧版本号，并同时兼容多个版本
【GET】 /v1/users/{user_id} // 版本 v1 的查询用户列表的 API 接口
【GET】 /v2/users/{user_id} // 版本 v2 的查询用户列表的 API 接口
2、资源路径
URI 不能包含动词，只能是名词（命名名词的时候，要使用小写、数字及下划线来区分多个单词）。
资源的路径应该从根到子依次如下:
/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}
【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用户的角色
有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。
/{resources}/{resource_id}/actions/{action}
【PUT】 /v1/users/{user_id}/password/actions/modify // 密码修改
3、请求方式
【GET】 /users # 查询用户信息列表
【GET】 /users/1001 # 查看某个用户信息
【POST】 /users # 新建用户信息
【PUT】 /users/1001 # 更新用户信息(全部字段)
【PATCH】 /users/1001 # 更新用户信息(部分字段)
【DELETE】 /users/1001 # 删除用户信息
【PATCH】一般不用，用【PUT】
4、查询参数
RESTful API 接口应该提供参数，过滤返回结果。
【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20
5、响应参数
JSON格式（code、data、msg）
6、状态码
使用适合的状态码很重要，而不应该全部都返回状态码 200
状态码，可根据以下标准按照项目扩展自身状态码：
200~299段 表示操作成功：
200 操作成功，正常返回
201 操作成功，已经正在处理该请求
300~399段 表示参数方面的异常
300 参数类型错误
301 参数格式错误
302 参数超出正常取值范围
303 token过期
304 token无效
400~499段 表示请求地址方面的异常：
404找不到地址
500~599段 表示内部代码异常：
500 服务器代码异常