Spring Boot入門系列（二十）快速打造Restful API 接口

2020 年 10 月 10 日
筆記
SpringBoot入門系列

spring boot入門系列文章已經寫到第二十篇，前面我們講了spring boot的基礎入門的內容，也介紹了spring boot 整合mybatis，整合redis、整合Thymeleaf 模板引擎等各種框架，同時也介紹了使用jdbcTemplate 操作數據庫，配置多數據源等系列內容。應該說spring boot 常用的功能基本上都覆蓋到了。接下來說一說spring boot 比較實用的項目級的功能。首先會介紹spring boot 如何快速打造Restful API接口。

隨着互聯網化等逐漸深入，應用系統也變得越來越複雜，系統架構正在朝着微服務化，中台化的方向發展。這就需要各個系統、各個廠家之間的數據頻繁交互。所以，使用 Restful 風格構建的應用接口適用於移動互聯網廠商的業務場景，正在被越來越多的企業推薦使用。那麼什麼是 RESTful 呢？

一、什麼是 RESTful

RESTful 是目前最流行的互聯網軟件架構。 REST（Representational State Transfer，表述性狀態轉移）一詞是由 Roy Thomas Fielding 在他 2000 年博士論文中提出的，定義了他對互聯網軟件的架構原則，如果一個架構符合 REST 原則，則稱它為 RESTful 架構。

RESTful 把服務器端，所有的應用程序狀態和功能定義為「資源」（Resource）。從 RESTful 的⻆度看，網絡上的任何東西都是資源，它可以是一段文本、一張圖片、一個服務等，每個資源都對應一個特定的 URI（統一資源定位符），並把它進行標示，訪問這個 URI 就可以獲得這個資源。

資源可以有多種表現形式，也就是資源的「表述」（Representation），比如一張圖片可以使用 JPEG 格式也可以使用 PNG 格式。 URI 只是代表了資源的實體，並不能代表它的表現形式。互聯網中，客戶端和服務端之間的互動傳遞的就是資源的表述，我們上網的過程，就是調用資源的 URI，獲取它不同表現形式的過程。這種互動只能使用無狀態協議 HTTP，也就是說，服務端必須保存所有的狀態，客戶端可以使用 HTTP 的幾個基本操作，包括 GET（獲取）、 POST（創建）、 PUT（更新）與DELETE（刪除），使得服務端上的資源發「狀態轉化」（State Transfer），也就是所謂的「表述性狀態轉移」。

Restful 相比於 SOAP 更加簡單明了，它並沒有一個明確的標準，而更像是一種設計的風格。

Restful 特點包括：

　　1、每一個URI代表1種資源；

　　2、客戶端使用GET、POST、PUT、DELETE4個表示操作方式的動詞對服務端資源進行操作：GET用來獲取資源，POST用來新建資源（也可以用於更新資源），PUT用來更新資源，DELETE用來刪除資源；

　　3、通過操作資源的表現形式來操作資源；

　　4、資源的表現形式是XML或者HTML；

　　5、客戶端與服務端之間的交互在請求之間是無狀態的，從客戶端到服務端的每個請求都必須包含理解請求所必需的信息。

二、Spring Boot 實現Restful 方案

Spring Boot 開發Restful j接口非常簡單，通過不同的註解來支持前端的請求，除了經常使用的@RestController 註解外，Spring Boot 還提了一些組合註解。這些註解來幫助簡化常用的 HTTP 方法的映射，並更好地表達被註解方法的語義。

Srping Boot 提供了與Rest 操作方式（GET、POST、PUT、DELETE）對應的註解：

　　1、@GetMapping，處理 Get 請求
　　2、@PostMapping，處理 Post 請求
　　3、@PutMapping，用於更新資源
　　4、@DeleteMapping，處理刪除請求
　　5、@PatchMapping，用於更新部分資源

@PutMapping 主要是用來更新整個資源的，@PatchMapping 主要表示更新部分字段

之前我們也介紹過，Spring Boot 提供了專門做數據處理的控制器：@RestController ，其實這些註解就是我們使用的 @RequestMapping 的簡寫版本：@GetMapping 其實就等於@RequestMapping(value = “/xxx”,method = RequestMethod.DELETE) 。

三、Spring Boot 快速實現Restful

如何創建Spring Boot 項目之前的文章裏面都有，這裡不在重複了。可以看我之前的系列文章：//www.cnblogs.com/zhangweizhong/category/1657780.html

1、設計接口

根據之前介紹的Restful 設計風格設計一組對用戶操作的 RESTful API

/user POST 創建用戶
/user/id GET 根據 id 獲取用戶信息
/user PUT 更新用戶
/user/id DELETE 根據 id刪除對應的用戶

以上，就是對user操作的接口定義，在實際項目的Restful API 接口文檔還會定義全部請求的數據結構體。

2、實現接口

首先創建UserController 控制器，定義之前設計的相關接口。

package com.weiz.controller;

import com.weiz.pojo.SysUser;
import com.weiz.service.UserService;
import com.weiz.utils.JSONResult;
import org.n3r.idworker.Sid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Date;

@RestController
@RequestMapping("/")
public class UserController {

    @Autowired
    private UserService userService;

    @Autowired
    private Sid sid;

    @PostMapping(value = "user")
    public JSONResult create() throws Exception {

        String userId = sid.nextShort();
        SysUser user = new SysUser();
        user.setId(userId);
        user.setUsername("spring boot" + new Date());
        user.setNickname("spring boot" + new Date());
        user.setPassword("abc123");
        user.setIsDelete(0);
        user.setRegistTime(new Date());

        userService.saveUser(user);
        return JSONResult.ok("保存成功");
    }

    @PutMapping(value = "user")
    public JSONResult update() {
        SysUser user = new SysUser();
        user.setId("10011001");
        user.setUsername("10011001-updated" + new Date());
        user.setNickname("10011001-updated" + new Date());
        user.setPassword("10011001-updated");
        user.setIsDelete(0);
        user.setRegistTime(new Date());
        userService.updateUser(user);

        return JSONResult.ok("保存成功");
    }


    @DeleteMapping("user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        userService.deleteUser(userId);
        return JSONResult.ok("刪除成功");
    }

    @GetMapping("user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        return JSONResult.ok(userService.queryUserById(userId));
    }

}

說明：

　　1、@PathVariable 註解，用於參數映射。

　　2、Rest需要注意請求的方式，可以看到PUT和POST的URL是相同的，但是後端處理邏輯不同，所以使用的時候千萬別搞混了。

3、測試
實際開發測試的過程中，一般使用postman測試相關的接口。當然，也可以用單元測試來實現。這裡簡單起見，直接用postman來測試剛剛定義的人員操作接口。

創建人員：/user

根據 id 獲取人員信息：/user/id

以上，測試了人員的創建和查詢接口，其他接口的測試也是一樣。

最後

以上，就把Spring Boot 實現Restful API 接口介紹完了。 Restful 是一種非常優雅的設計，採用RESTful 設計API之後 /user/api一個URL地址解決，前端一看就能明白。

這個系列課程的完整源碼，也會提供給大家。大家關注我的微信公眾號（架構師精進），回復：springboot源碼。獲取這個系列課程的完整源碼。

Tags: SpringBoot入門系列