通俗易懂的RESTful API实践详解（含代码）

曾经终败给现在 2022-04-03 03:08 296阅读 0赞

### **一、什么是RESTful** ###

REST 是面向资源的，这个概念非常重要，而资源是通过 URI 进行暴露，URI 的设计只要负责把资源通过合理方式暴露出来就可以了，对资源的操作与它无关，操作是通过 HTTP动词来体现。所以**REST 通过 URI 暴露资源时，会强调不要在 URI 中出现动词，而是对一类资源只提供一个url，通过GET、POST、PUT、DELETE请求来指定要执行的操作**。

非RESTful 用法（多个url且url中存在动词）

http://127.0.0.1/order/query/1 GET  根据订单id查询订单数据
    http://127.0.0.1/order/save POST 新增订单
    http://127.0.0.1/order/update POST 修改订单信息
    http://127.0.0.1/order/delete GET/POST 删除订单信息

RESTful 用法（同一个url，具体的操作通过HTTP请求方式来指定）

http://127.0.0.1/order/1 GET  根据订单id查询订单数据
    http://127.0.0.1/order  POST 新增订单
    http://127.0.0.1/order  PUT 修改订单信息
    http://127.0.0.1/order  DELETE 删除订单信息

REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等。  
        REST API 是基于 HTTP的，所以你的API应该去使用 HTTP的一些标准。这样所有的HTTP客户端（如浏览器）才能够直接理解你的API。

**REST返回值是标准的，我们不用单独定义和封装返回的状态码，而是直接使用HTTP的状态码**，非RESTful 返回举例：

{
      "code": "0",
      "msg": "成功"
    }

{
      "code": "1",
      "msg": "失败"
    }

这种方式还要我们自己去解析，还要前端和后端去协商你返回的0是啥意思。

### 二、**RESTful 的关键** ###

RESTful的关键是定义可表示流程元素/资源的对象。在REST中，每一个对象都是通过URL来表示的，对象用户负责将状态信息打包进每一条消息内，以便对象的处理总是**无状态**的。**前后端分离的项目基本上就是无状态的，我们经常通过签名判断当前的请求是否合法**。

所谓无状态的，即所有的资源，都可以通过URI定位，而且这个定位与其他资源无关，也不会因为其他资源的变化而改变。

举个简单的例子说明一下有状态和无状态的区别，如查询员工的工资，如果查询工资是需要登录系统，进入查询工资的页面，执行相关操作后，获取工资的多少，则这种情况是有状态的，因为查询工资的每一步操作都依赖于前一步操作，只要前置操作不成功，后续操作就无法执行；如果输入一个url即可得到指定员工的工资，则这种情况是无状态的，因为获取工资不依赖于其他资源或状态，且这种情况下，员工工资是一个资源，由一个url与之对应，可以通过HTTP中的GET方法得到资源，这是典型的RESTful风格。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0xEWTEwMTY_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0xEWTEwMTY_size_16_color_FFFFFF_t_70 1][]

### **三、RESTful API代码示例** ###

package com.ldy.sboot.demo.controller;
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import com.ldy.sboot.demo.entity.OrderEntity;
 import com.ldy.sboot.demo.service.OrderService;
 
 @RequestMapping("restful/order")
 @RestController
 public class OrderController {
 
 @Autowired
 private OrderService orderService;
 
 /**
 * @描述: 根据ID查询 
 * @param id
 * @return
 */
 @GetMapping(value = "{id}")
 //@RequestMapping(method = RequestMethod.GET)
 public ResponseEntity<OrderEntity> queryOrderById(@PathVariable("id") Long id) {
 try {
 OrderEntity entity = orderService.queryOrderById(id);
 if (null == entity) {
 // 资源不存在，响应404
 return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
 }
 // 200
 // return ResponseEntity.status(HttpStatus.OK).body(entity);
 return ResponseEntity.ok(entity);
 } catch (Exception e) {
 e.printStackTrace();
 }
 // 500
 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
 }
 
 /**
 * @描述: 新增 
 * @param entity
 * @return
 */
 @PostMapping
 //@RequestMapping(method = RequestMethod.POST)
 public ResponseEntity<Void> saveOrder(OrderEntity entity) {
 try {
 orderService.saveOrder(entity);
 return ResponseEntity.status(HttpStatus.CREATED).build();
 } catch (Exception e) {
 // TODO Auto-generated catch block
 e.printStackTrace();
 }
 // 500
 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
 }
 
 /**
 * @描述: 修改 
 * @param entity
 * @return
 */
 @PutMapping
 //@RequestMapping(method = RequestMethod.PUT)
 public ResponseEntity<Void> updateOrder(OrderEntity entity) {
 try {
 orderService.updateOrder(entity);
 return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
 } catch (Exception e) {
 e.printStackTrace();
 }
 // 500
 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
 }
 
 /**
 * @描述: 删除 
 * @param id
 * @return
 */
 @DeleteMapping
 //@RequestMapping(method = RequestMethod.DELETE)
 public ResponseEntity<Void> deleteOrder(@RequestParam(value = "id") Long id) {
 try {
 OrderEntity entity = orderService.queryOrderById(id);
 if (null == entity) {
 // 不存在返回404
 return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
 }
 orderService.deleteOrderById(id);
 // 204
 return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
 } catch (Exception e) {
 e.printStackTrace();
 }
 // 500
 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
 }
 }

### **四、 HTTP状态码说明** ###

<table> 
 <thead> 
 <tr> 
 <th style="width:79px;">状态码</th> 
 <th style="width:140px;">状态码英文名称</th> 
 <th>中文描述</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td colspan="3">1开头的状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">100</td> 
 <td style="width:140px;">Continue</td> 
 <td>继续。客户端应继续其请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">101</td> 
 <td style="width:140px;">Switching Protocols</td> 
 <td>切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议</td> 
 </tr> 
 <tr> 
 <td colspan="3">2开头的状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">200</td> 
 <td style="width:140px;">OK</td> 
 <td>请求成功。一般用于GET与POST请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">201</td> 
 <td style="width:140px;">Created</td> 
 <td>已创建。成功请求并创建了新的资源</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">202</td> 
 <td style="width:140px;">Accepted</td> 
 <td>已接受。已经接受请求，但未处理完成</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">203</td> 
 <td style="width:140px;">Non-Authoritative Information</td> 
 <td>非授权信息。请求成功。但返回的meta信息不在原始的服务器，而是一个副本</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">204</td> 
 <td style="width:140px;">No Content</td> 
 <td>无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">205</td> 
 <td style="width:140px;">Reset Content</td> 
 <td>重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">206</td> 
 <td style="width:140px;">Partial Content</td> 
 <td>部分内容。服务器成功处理了部分GET请求</td> 
 </tr> 
 <tr> 
 <td colspan="3">3开头的状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">300</td> 
 <td style="width:140px;">Multiple Choices</td> 
 <td>多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">301</td> 
 <td style="width:140px;">Moved Permanently</td> 
 <td>永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">302</td> 
 <td style="width:140px;">Found</td> 
 <td>临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">303</td> 
 <td style="width:140px;">See Other</td> 
 <td>查看其它地址。与301类似。使用GET和POST请求查看</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">304</td> 
 <td style="width:140px;">Not Modified</td> 
 <td>未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">305</td> 
 <td style="width:140px;">Use Proxy</td> 
 <td>使用代理。所请求的资源必须通过代理访问</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">306</td> 
 <td style="width:140px;">Unused</td> 
 <td>已经被废弃的HTTP状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">307</td> 
 <td style="width:140px;">Temporary Redirect</td> 
 <td>临时重定向。与302类似。使用GET请求重定向</td> 
 </tr> 
 <tr> 
 <td colspan="3">4开头的状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">400</td> 
 <td style="width:140px;">Bad Request</td> 
 <td>客户端请求的语法错误，服务器无法理解</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">401</td> 
 <td style="width:140px;">Unauthorized</td> 
 <td>请求要求用户的身份认证</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">402</td> 
 <td style="width:140px;">Payment Required</td> 
 <td>保留，将来使用</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">403</td> 
 <td style="width:140px;">Forbidden</td> 
 <td>服务器理解请求客户端的请求，但是拒绝执行此请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">404</td> 
 <td style="width:140px;">Not Found</td> 
 <td>服务器无法根据客户端的请求找到资源（网页）。通过此代码，网站设计人员可设置"您所请求的资源无法找到"的个性页面</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">405</td> 
 <td style="width:140px;">Method Not Allowed</td> 
 <td>客户端请求中的方法被禁止</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">406</td> 
 <td style="width:140px;">Not Acceptable</td> 
 <td>服务器无法根据客户端请求的内容特性完成请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">407</td> 
 <td style="width:140px;">Proxy Authentication Required</td> 
 <td>请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">408</td> 
 <td style="width:140px;">Request Time-out</td> 
 <td>服务器等待客户端发送的请求时间过长，超时</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">409</td> 
 <td style="width:140px;">Conflict</td> 
 <td>服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">410</td> 
 <td style="width:140px;">Gone</td> 
 <td>客户端请求的资源已经不存在。410不同于404，如果资源以前有现在被永久删除了可使用410代码，网站设计人员可通过301代码指定资源的新位置</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">411</td> 
 <td style="width:140px;">Length Required</td> 
 <td>服务器无法处理客户端发送的不带Content-Length的请求信息</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">412</td> 
 <td style="width:140px;">Precondition Failed</td> 
 <td>客户端请求信息的先决条件错误</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">413</td> 
 <td style="width:140px;">Request Entity Too Large</td> 
 <td>由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">414</td> 
 <td style="width:140px;">Request-URI Too Large</td> 
 <td>请求的URI过长（URI通常为网址），服务器无法处理</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">415</td> 
 <td style="width:140px;">Unsupported Media Type</td> 
 <td>服务器无法处理请求附带的媒体格式</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">416</td> 
 <td style="width:140px;">Requested range not satisfiable</td> 
 <td>客户端请求的范围无效</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">417</td> 
 <td style="width:140px;">Expectation Failed</td> 
 <td>服务器无法满足Expect的请求头信息</td> 
 </tr> 
 <tr> 
 <td colspan="3">5开头的状态码</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">500</td> 
 <td style="width:140px;">Internal Server Error</td> 
 <td>服务器内部错误，无法完成请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">501</td> 
 <td style="width:140px;">Not Implemented</td> 
 <td>服务器不支持请求的功能，无法完成请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">502</td> 
 <td style="width:140px;">Bad Gateway</td> 
 <td>充当网关或代理的服务器，从远端服务器接收到了一个无效的请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">503</td> 
 <td style="width:140px;">Service Unavailable</td> 
 <td>由于超载或系统维护，服务器暂时的无法处理客户端的请求。延时的长度可包含在服务器的Retry-After头信息中</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">504</td> 
 <td style="width:140px;">Gateway Time-out</td> 
 <td>充当网关或代理的服务器，未及时从远端服务器获取请求</td> 
 </tr> 
 <tr> 
 <td style="width:79px;">505</td> 
 <td style="width:140px;">HTTP Version not supported</td> 
 <td>服务器不支持请求的HTTP协议的版本，无法完成处理</td> 
 </tr> 
 </tbody> 
</table>

推荐文档：[https://blog.igevin.info/posts/restful-architecture-in-general/][https_blog.igevin.info_posts_restful-architecture-in-general]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0xEWTEwMTY_size_16_color_FFFFFF_t_70]: /images/20220403/e437af16a6094a5596637addf5bf5654.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0xEWTEwMTY_size_16_color_FFFFFF_t_70 1]: /images/20220403/a19cc16315e846ed82a33abea44cd51e.png
[https_blog.igevin.info_posts_restful-architecture-in-general]: https://blog.igevin.info/posts/restful-architecture-in-general/