使用SpringBoot框架開發POST接口

SpringBoot 專案的分層#

SpringBoot 框架專案一般分為五層：

View 層：向用戶展示頁面
Controller 層：前後端交互層，接收前端請求，調用 Service 層中的方法，接收 Service 層返回的數據並將其返回到前端。
Service 層：存放業務處理的邏輯，以及一些操作資料庫的介面
Mapper 層：也可以稱為 DAO 層，是資料庫 CRUD 的介面，只有方法名，具體實現在 mapper.xml 文件中，對資料庫進行數據持久化操作
Entity 層：存放實體類，與資料庫中的屬性基本保持一致。

實現一個最簡單的 POST 介面#

一個最簡單的 POST 介面，只需要在 Controller 層中聲明一個 RestController 類，隨後在類中使用 PostMapping 註解，表明這是一個 POST 介面，並填寫相關方法即可，如下所示：

@RestController
@RequestMapping("/api")
public class CreateNumberController {
    @PostMapping("/number")
    public String createNumber(@RequestParam String param1, @RequestParam int param2) {
        // 處理POST請求的代碼
        return "success";
    }
}

運行程序後，使用 Postman 向http://localhost:8000/api/number發送 POST 請求，輸入相應請求參數，得到介面響應：

基礎介面響應

將介面連接事務處理邏輯函數#

實際業務中的介面肯定不僅僅是如同上面的示例那麼簡單的一個函數，程序內部對於接收到的數據會有一定的邏輯處理。

接下來列出一個實際的業務場景：

需求#

現在需要一個介面用於按照一定規則為專案賦予專案編碼，專案請求內容為 xml 報文，例如：
<?xml version="1.0" encoding="UTF-8"?>
<name>示例專案</name>
<operate>01</operate>
<source>A</source>
<status>01</status>
當請求參數 operate 是 1 時為新增專案編碼，請求參數 source 是 A、B、C 時，專案編碼為 Axxxx，“xxxx” 为四位包含「0~9 的 10 個阿拉伯數字」和「A~Z 的 26 個大寫英文字母」共同組成的流水碼次序為：0/1/2/3/4/5/6/7/8/9/A/B/C/D~/X/Y/Z，增加 2 條約束：

①第 5 位、第 4 位與第 3 位從 000 開始取值，第 2 位從 B 開始取值，即初始編碼為：AB000；第 5 位至第 2 位，每一位的取值範圍為「0~9 的 10 個阿拉伯數字」和「A~Z 的 24 個大寫英文字母（26 個字母中去除 I 和 O）」的 34 個字符，順序依次為 0/1/2/3/4/5/6/7/8/9/A/B/C/D~/X/Y/Z，此時 “xxxx” 为 34 進制的 4 位數。第 5 位 0 至 Z 循環一周期後即向第 4 位進 1，第 4 位循環一周期後即向第 3 位進 1，第 3 位循環一周期後向第 2 位進 1。

②第 2 位除了 I 和 O 之外，A、C、Z 也不可取，循環取值從 B 開始至 A 結束，依次為 B/D…G/H/J/K…M/N/P…X/Y/0/1…9 共計 31 個字符。

要求返回值為 xml 報文，形式為：
<?xml version="1.0" encoding="UTF-8"?>
<number>AB000</number>
<status>01</status>

由於暫未規定如何校驗重複編碼（這個需要用到資料庫查詢，在接下來的部分繼續補充），因此可以將需求簡單理解為：接收一個 xml 報文，按照規則生成一個編碼，返回編碼。

這時介面的輸入和輸出都是 xml 報文，僅僅依靠簡單的 Controller 已經不能滿足需求了，需要將輸入報文進行處理拆分對應的參數，依靠 Service 對輸入數據進行處理，使用函數生成符合要求的輸出，並最終封裝成 xml 報文返回。

POST 介面接收 XML 報文#

通常來說，在進行介面設計時思考問題是自頂向下的，即 “介面可以接收並解析請求體→調用 Service 使用請求體中的數據運行業務邏輯→將得到的結果封裝完成響應”。但實際的開發步驟是：根據需求明確請求體和響應體包括哪些屬性以及這些屬性的數據類型，構造請求類與響應類→新增 Service 類編寫請求類的處理邏輯和響應類的生成邏輯→新增 Controller 類添加 POST 介面可以接收 XML 報文並在經過 Service 處理後返回 XML 報文。

導入相關依賴#

處理 xml 報文需要 Gradle 導入 jackson-dataformat-xml 依賴，為保證專案的可遷移性與可重用性，放棄引入 Lombok。

在 Maven 倉庫（例如https://mvnrepository.com/）中搜索 jackson-dataformat-xml 依賴，選擇 Gradle，將下面這行複製進 build.gradle 的 dependencies 部分：

implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.15.2'

Jackson 庫會自動將 XML 元素映射到同名的 Java 屬性。

導入到 Gradle

創建 Request 類和 Response 類#

根據請求報文，在 Controller 文件夾中新增 ProjectNumberRequest 類和 ProjectNumberResponse 類，分別如下：

ProjectNumberRequest.java

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;

public class ProjectNumberRequest {
    private String name;
    private String operate;
    private String source;
    private String status;
    
    //get方法
    public String getName() {
        return this.name;
    }
    public String getOperate() {
        return this.operate;
    }
    public String getSource() {
        return this.source;
    }
    public String getStatus() {
        return this.status;
    }
    
    //set方法
    public void setName(String projectName) {
        this.name = projectName;
    }
    public void setOperate(String projectOperate) {
        this.operate = projectOperate;
    }
    public void setSource(String projectSource) {
        this.source = projectSource;
    }
    public void setStatus(String projectStatus) {
        this.status = projectStatus;
    }
}

ProjectNumberResponse.java

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;

@JacksonXmlRootElement(localName = "response")
public class ProjectNumberResponse {
    private String number;
    private String status;

    //get方法
    public String getNumber() {
        return this.number;
    }
    public String getStatus() {
        return this.status;
    }

    //set方法
    public void setNumber(String number) {
        this.number = number;
    }
    public void setStatus(String projectStatus) {
        this.status = projectStatus;
    }
}

注意：諸如@JacksonXmlRootElement(localName = "response")的註解可以將 XML 的根節點重命名為 response，如果不添加註解則 XML 文件根節點名稱默認使用類名。

編寫業務邏輯#

在 Service 文件夾下新增 CreateNumberService 類，用於處理請求報文的請求體，並按照一定規則生成專案編碼和專案狀態這兩個屬性，將其轉換為 XML 文件，組成響應報文的響應體。

CreateNumberService 包括兩部分，第一部分是 response 對象生成函數，用於創建響應體對象，第二部分是 XML 對象生成函數，用於將 response 對象封裝成 XML 對象。

CreateNumberService.java

import com.fasterxml.jackson.dataformat.xml.XmlMapper;
import org.springframework.stereotype.Service;
import studio.tsukistar.demo.Controller.ProjectNumberRequest;
import studio.tsukistar.demo.Controller.ProjectNumberResponse;

import java.util.Objects;
@Service
public class CreateNumberService {
    private static final String XML_HEAD = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
    
    public String createService(ProjectNumberRequest request) { //構建response對象
        ProjectNumberResponse response = new ProjectNumberResponse();
        response.setNumber( "AB000" );
        response.setStatus(request.getStatus());
        return javaBeanToXml (response);
    }
    
    public static String javaBeanToXml(Object obj) { //將Object轉換為xml形式
        String xml= "";
        if (Objects.isNull(obj)) {
            return xml;
        }
        
        try {
            XmlMapper xmlMapper = new XmlMapper();
            xml = xmlMapper.writeValueAsString(obj);
        } catch (Exception e) {
            return "";
        }
        
        return XML_HEAD + xml;
    }
}

編寫控制器#

在 Controller 文件夾下新增 CreateNumberController 類，設置請求體傳入類型為 XML 格式，返回經過 CreateNumberService 處理請求體後得到的響應報文。

CreateNumberController.java

import jakarta.annotation.Resource;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import studio.tsukistar.demo.Service.CreateNumberService;

@RestController
@RequestMapping("/api")
public class CreateNumberController {
    @Resource
    private CreateNumberService numberService;

    @PostMapping(value="/number", produces = MediaType.APPLICATION_XML_VALUE)
    public String createNumber(@RequestBody ProjectNumberRequest request) { // 處理POST請求的代碼
        return numberService.createService(request);
    }
}

運行測試#

運行程序後，使用 Postman 向http://localhost:8000/api/number發送 POST 請求，在 “Body” 中選擇 “raw-XML”，填入請求體：

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <name>測試</name>
    <operate>01</operate>
    <source>A</source>
    <status>01</status>
</request>

點擊 “Send” 可以得到介面的響應報文，如下圖所示：

測試結果

總結#

相較於上次，這段時間新學習了 POST 介面的開發方式、專案分層、各層之間的交互等內容，對 SpringBoot 框架也有了更深入的了解（也許？希望不要誤入歧途）。代碼也一並傳到了 github 倉庫中，向前邁進了一大步。

本文多數開發知識來源於 Bing AI，若有錯誤之處請各位 dalao 多多指教，不勝感激！

月落星河Tsukistar