RESTful API实践详解

一、什么是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风格。

三、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查询<br>
     * @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);
    }
 
    /**
     * @描述: 新增<br>
     * @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);
    }
 
    /**
     * @描述: 修改<br>
     * @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);
    }
 
    /**
     * @描述: 删除<br>
     * @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);
    }
}