使用SpringBoot開發一個POST介面

SpringBoot項目的分層 SpringBoot框架項目一般分為五層： View層：向用戶展示頁面 Controller層：前後端交互層，接收前端請求，調用Service層中的方法，接收Service層返回的數據並將其返回到前端。 Service層：存放業務處理的邏輯，以及一些操作資料庫的介面 ...

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>Example Project</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多多賜教，不勝感激！