教你 10 分鐘構建一套 RESTful API 服務 ( 上 )

1. 前言

隨著前後端分離和微服務的興起，在後端開發中，RESTful API 幾乎變成一種標配

RESTful API 是一套成熟的網際網路應用程式設計風格及開發方式，其最重要的 3 個特徵如下：

1、無狀態，客戶端與服務端之間的互動在請求之間是無狀態的

2、統一介面，伺服器和客戶端的通訊方法必須保持統一

3、基於資源，增刪改查都是對於資源狀態的改變

接下來，將分兩篇文章，教大家用  Java 和 Python 快速構建一套 RESTful API

本篇將從 Java - RESTful API 開始，使用的技術棧是：SpringBoot + MyBatis + Swagger2

2. 準備

第 1 步，下載安裝 IDEA 開發工具

https://www.jetbrains.com/idea/

然後，新建一個 Spring Boot 專案

第 2 步，輸入包名，然後選擇構建方式，其他保持預設即可

預設構建方式是：Maven，可以手動切換到 Gradle，本文以 Maven 為例

第 3 步，工程專案為 Web 專案，選擇 Spring Boot 的版本及專案儲存位置

第 4 步，按照功能，使用包名對專案進行分層

對專案進行分層，新建一些常用的包，包含：service、controller、domain 等

第 5 步，為工程新增 Maven 依賴

編寫專案根目錄下的 pom.xml 檔案，新增對 MyBatis、Mysql、Swagger 的 Maven 依賴，重新構建，等待所有依賴下載完成

# pom.xml
# maven 依賴
<!--Swagger-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.7.0</version>
</dependency>

<!--MyBatis-->
<dependency>
     <groupId>org.mybatis.spring.boot</groupId>
     <artifactId>mybatis-spring-boot-starter</artifactId>
     <version>2.1.2</version>
</dependency>

<!--MySql-->
<dependency>
     <groupId>mysql</groupId>
     <artifactId>mysql-connector-java</artifactId>
     <version>6.0.6</version>
</dependency>

第 6 步，配置資料庫

在本機安裝資料庫，以 Mysql 為例，並新建一個資料庫、設計一個表，表的結構如下：

修改配置檔案 application.properties，配置對應的資料庫資訊，包含：地址、使用者名稱、密碼等

# application.properties
# 資料庫配置資訊
spring.datasource.url=jdbc:mysql://localhost:3306/dg?useSSL=false
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.data.elasticsearch.client.reactive.use-ssl=false

3. 實現

具體實現 RESTful API 過程如下：

第 1 步，新建一個實體類 People，實體成員變數與上面表結構欄位一一對應

package com.xingag.api.domain;
/***
 * 資料庫對映物件
 */
public class People {
    private int id;
    private String name;
    private int age;
    private boolean extra;

    public People() {
    }

    public People(int id, String name, int age, boolean extra) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.extra = extra;
    }

   // ... 省略成員變數的get/set方法
}

第 2 步，MyBatis 資料庫對映

以 CRUD 為例，即：查詢所有記錄、查詢某一條記錄、插入一條記錄、更新一條記錄、刪除一條記錄

使用 MyBatis 的 4 個註解，包含：@Select、@Update、@Insert、@Delete 結合 SQL 語句，對映對應的方法，到達運算元據庫的動作

// PeopleHandle.java
@Mapper
public interface PeopleHandle {

    /***
     * 查詢資料表中的所有記錄
     * 對應SQL：select * from people
     * @return
     */
    @Select("SELECT * FROM PEOPLE")
    List<People> getAllPeople();

    /***
     * 查詢資料表中的某一條記錄
     * @param id 查詢的id
     * @return
     */
    @Select("SELECT * FROM PEOPLE where ID = #{id}")
    People getPeople(@Param("id") int id);

    /***
     * 插入一條資料
     * @param name 姓名
     * @param age  年齡
     * @param extra  其他
     * @return
     */
    @Insert("INSERT INTO PEOPLE(NAME,AGE,EXTRA) VALUES(#{name},#{age},#{extra})")
    int insertPeople(@Param("name") String name, @Param("age") int age, @Param("extra") boolean extra);


    /***
     * 更新一條記錄（@UpdateProvider）
     * @param people 準備更新進去的資料
     * @return
     */
    @UpdateProvider(type = SqlProvider.class, method = "updatePeopleSql")
    int updatePeople(People people);

    /***
     * 刪除某條記錄（@Delete）
     * @param id 根據ID去刪除一條記錄
     * @return
     */
    @Delete("DELETE FROM PEOPLE WHERE ID = #{id}")
    int deletePeople(@Param("id") int id);
}

需要注意的是，更新操作藉助了 MyBatis 裡的 @UpdateProvider 註解，指向 SqlProvider 類的 updatePeopleSql 方法，動態生成 SQL，使用起來更加靈活

// SqlProvider.java
public class SqlProvider {

    /***
     * 使用MyBatis的SQL方法來更新sql語句
     *
     * @return
     */
    public String updatePeopleSql(People people) {

        //包含表名，要更新的欄位，更新條件（id）
        //最後組裝成新的SQL語句
        return new SQL() {{
            UPDATE("people");

            if (null != people.getName()) {
                SET("name=#{name}");
            }
            SET("age=#{age}");
            SET("extra=#{extra}");
            WHERE("id=#{id}");
        }}.toString();
    }
}

第 3 步，編寫服務 Service

新建一個 PeopleService 介面，定義對外提供的方法

// PeopleService.java
/***
 * 對外提供的介面
 */
public interface PeopleService {
    //獲取所有的資料
    List<People> getAllPeoples();

    //獲取某一條記錄
    People getOnePeople(int id);

    //更新一條記錄
    boolean updatePeople(People people);

    //新增一條記錄
    boolean addPeople(People people);

    //刪除一條記錄
    boolean delPeople(int id);
}

第 4 步，實現服務

新建服務實現類 PeopleServiceImp 使用 @Autowired 註解自動匯入上面定義的資料庫對映操作介面：PeopleHandle

​@Service
public class PeopleServiceImp implements PeopleService {

    //匯入
    @Autowired
    private PeopleHandle peopleHandle;
}

在服務類中，實現上面介面定義的功能

@Override
public List<People> getAllPeoples() {
     return peopleHandle.getAllPeople();
}

@Override
public People getOnePeople(int id) {
     return peopleHandle.getPeople(id);
}

@Override
public boolean updatePeople(People people) {
     return peopleHandle.updatePeople(people) > 0;
}

@Override
public boolean addPeople(People people) {
     return peopleHandle.insertPeople(people.getName(),people.getAge(),people.isExtra())>0;
}

@Override
public boolean delPeople(int id) {
     return peopleHandle.deletePeople(id)>0;
}

第 5 步，暴露介面 Controller

首先，新建一個檔案 PeopleController，用於對外暴露介面

@RestController
@RequestMapping("/v1")
public class PeopleController {
    //...
}

其中，@RestController 相當於 @Controller + @ResponseBody，快速將一個物件進行序列化後進行返回

@RequestMapping("/v1") 用於將請求路徑對映到整個類上

然後，利用 @RequestMapping 定義具體的路徑及請求的方式，這裡將需要暴露出去的介面都通過方法展示出來

以查詢某一條記錄為例，通過引數 id，使用 PeopleService 查詢到資料，返回即可。

PS：受限於篇幅，其他查詢所有記錄、更新、新增、刪除的程式碼在文末獲取原始碼

/***
 * 某一條記錄
 * @param id
 * @return
 */
@ApiOperation(value = "查詢某一條記錄")
@RequestMapping(value = "/one/{id}", method = RequestMethod.GET)
public ApiResult getOnePeople(@ApiParam(name = "id", value = "主鍵id", required = true) @PathVariable int id) {
    People people = peopleService.getOnePeople(id);
    if (null != people) {
         return ApiResult.success(people);
     } else {
         return ApiResult.failure("資料不存在");
     }
 }

第 6 步，返回資料標準化

為了方便後期維護，最後將 REST API 介面的結果進行一次封裝

使用 Lombok 結合 swagger，將返回碼、返回值等資料封裝到方法內部進行返回，並根據程式碼自動生成介面文件

@Data
@ApiModel(value = "介面返回結果")
public class ApiResult<T> implements Serializable {

    private static final long serialVersionUID = -2953545018812382877L;

    /**
     * 返回碼，200 正常
     */
    @ApiModelProperty(value = "返回碼，200 正常", name = "code")
    private int code = 200;

    /**
     * 返回資訊
     */
    @ApiModelProperty(value = "返回資訊", name = "msg")
    private String msg = "成功";

    /**
     * 返回資料
     */
    @ApiModelProperty(value = "返回資料物件", name = "data")
    private T data;

    /**
     * 獲取成功狀態結果
     *
     * @param data 返回資料
     * @return
     */
    public static ApiResult success(Object data) {
        return success(data, null);
    }


    /**
     * 獲取失敗狀態結果
     *
     * @param msg (自定義)失敗訊息
     * @return
     */
    public static ApiResult failure(String msg) {
        return failure(ResponseCode.FAIL.getCode(), msg, null);
    }
}

4. 視覺化

執行專案後，Spring Boot 自帶的 Tomcat 會以 8080 埠號執行

使用瀏覽器訪問

http://localhost:8080/swagger-ui.html

由於專案中整合了 Swagger，這裡可以很直觀的看到定義好的 RESTful API

5. 最後

上面實現的 RESTful API，可以通過 CURL 或者 Postman 去測試，去一步步完善

下一篇文章將講解 Python 中搭建 RESTful API 正確的姿勢

如果你覺得文章還不錯，請大家點贊分享下。你的肯定是我最大的鼓勵和支援。