實戰：基於Spring Boot快速開發RESTful風格API接口

寫在前面的話

這篇文章計劃是在過年期間完成的，示例代碼都寫好了，結果親戚來我家做客，文章沒來得及寫。已經很久沒有更新文章了，小夥伴們，有沒有想我啊。言歸正傳，下面開始，今天的話題。

目標

寫一套符合規範，並且具有RESTful風格的API接口。

假定

你已會使用Spring Boot 2.x。
你已會使用Gradle構建Spring Boot工程。
你已會基於Spring Boot編寫API接口。
你已會使用接口調試工具。

如果你還不會使用Spring Boot寫接口，建議先看一下這篇文章：

用Spring Boot開發API接口

步驟

1、基於Gradle構建Spring Boot示例項目。

2、引入JavaLib。

3、編寫接口代碼。

4、測試接口。

引入JavaLib

測試版(SNAPSHOT)，都會發布到 JitPack 上，所以，從這裏拉取的，都會是最新的，但是需要配置倉庫地址。

正式版(RELEASE)，纔會推送到 Maven中央。

UserModel

我們用UserModel來存放我們的數據，以便存取。我個人比較喜歡用bean的，如果你喜歡用Map，那也是可以的。不過需要注意的是，
需要加@JsonInclude(JsonInclude.Include.NON_NULL) ，他的作用是，如果某個字段爲空時，在返回的JSON中，則不顯示，如果沒有，將爲 null。

完整代碼如下：

package com.fengwenyi.demojavalibresult.model;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
import lombok.experimental.Accessors;

import java.io.Serializable;

/**
 * User Model
 * @author Wenyi Feng
 * @since 2019-02-05
 */
@Data
@Accessors(chain = true)
@JsonInclude(JsonInclude.Include.NON_NULL)
public class UserModel implements Serializable {

    private static final long serialVersionUID = -835481508750383832L;

    /** UID */
    private String uid;

    /** Name */
    private String name;

    /** Age */
    private Integer age;

}

編寫接口返回碼

這裏我們使用 JavaLib 中result模塊爲我們提供的方法。只需要調用 BaseCodeMsg.app(Integer, String)即可。這裏我們只寫幾個用作示例，完整代碼如下：

package com.fengwenyi.demojavalibresult.util;

import com.fengwenyi.javalib.result.BaseCodeMsg;

/**
 * 自定義返回碼以及描述信息
 * @author Wenyi Feng
 * @since 2019-02-05
 */
public class CodeMsg {

    /*
    user error
    ------------------------------------------------------------------------------------------------------------*/
    /** 用戶不存在 */
    public static final BaseCodeMsg ERROR_USER_NOT_EXIST = BaseCodeMsg.app(10001, "User Not Exist");

    /** UID不能爲空 */
    public static final BaseCodeMsg ERROR_USER_UID_NOT_NULL = BaseCodeMsg.app(10002, "User UID Must Not null");

}

BaseCodeMsg

我們看一下源碼：

package com.fengwenyi.javalib.result;

/**
 * （基類）返回碼及描述信息
 * @author Wenyi Feng
 * @since 2019-01-22
 */
public class BaseCodeMsg {

    /** 返回碼 */
    private Integer code;

    /** 返回碼描述 */
    private String msg;

    /**
     * 無參數構造方法
     */
    private BaseCodeMsg() {}

    /**
     * 構造方法
     * @param code
     * @param msg
     */
    private BaseCodeMsg(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }


    public static BaseCodeMsg app(Integer code, String msg) {
        return new BaseCodeMsg(code, msg);
    }

    /**
     * 返回碼填充
     * @param args 填充內容
     * @return CodeMsgEnum
     */
    public BaseCodeMsg fillArgs(Object ... args) {

        this.msg = String.format(this.msg, args);

        return this;
    }

    /**
     * 獲取返回碼
     * @return 返回碼
     */
    public Integer getCode() {
        return code;
    }

    /**
     * 獲取描述信息
     * @return 描述信息
     */
    public String getMsg() {
        return msg;
    }

    /** 成功 */
    public static final BaseCodeMsg SUCCESS = BaseCodeMsg.app(0, "Success");

    /** 失敗 */
    public static final BaseCodeMsg ERROR_INIT = BaseCodeMsg.app(-1, "Error");
}

成功的標識是：當 code=0 時。

另外，我們還爲你提供了預留字符串替換的方法。比如你想告訴用戶某個字段不合法，那麼你可以這樣：

第一步：在CodeMsg中添加

public static final BaseCodeMsg ERROR_PARAM_ILLEGAL = BaseCodeMsg.app(20001, "Request Param Illegal : %s");

第二步：返回

    /**
     * 測試參數錯誤
     * @return {@link Result}
     */
    @GetMapping("/test-param-error")
    public Result testParamError() {
        return Result.error(CodeMsg.ERROR_PARAM_ILLEGAL.fillArgs("account"));
    }

測試結果：

編寫接口代碼

接下來，開始編寫我們的接口代碼。

首先指明，我們的接口接收和返回的文檔格式。

consumes = MediaType.APPLICATION_JSON_UTF8_VALUE
produces = MediaType.APPLICATION_JSON_UTF8_VALUE

再使用 JavaLib 中 Result。完整代碼如下：

package com.fengwenyi.demojavalibresult.controller;

import com.fengwenyi.demojavalibresult.model.UserModel;
import com.fengwenyi.demojavalibresult.util.CodeMsg;
import com.fengwenyi.javalib.result.Result;
import org.springframework.http.MediaType;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.*;

import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

/**
 * User Controller : 用戶操作
 * @author Wenyi Feng
 * @since 2019-02-05
 */
@RestController
@RequestMapping(value = "/user",
        consumes = MediaType.APPLICATION_JSON_UTF8_VALUE,
        produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class UserController {

    /** 臨時存放用戶信息 */
    private List<UserModel> userModelList = new ArrayList<>();

    /**
     * 初始化用戶
     */
    @PostConstruct
    public void init() {
        for (int i = 0; i < 10; i++)
            userModelList.add(new UserModel().setUid(UUID.randomUUID().toString()).setName("u" + i).setAge(10 + i));
    }

    /**
     * 查詢用戶列表
     * @return {@link Result}
     */
    @GetMapping("/list")
    public Result list() {
        return Result.success(userModelList);
    }

    /**
     * 添加用戶
     * @param userModel 這裏傳JSON字符串
     * @return {@link Result}
     */
    @PostMapping("/add")
    public Result add(@RequestBody UserModel userModel) {
        if (userModel != null) {
            userModelList.add(userModel.setUid(UUID.randomUUID().toString()));
            return Result.success();
        }
        return Result.error();
    }

    /**
     * 根據UID獲取用戶
     * @param uid UID
     * @return {@link Result}
     */
    @GetMapping("/get/{uid}")
    public Result getByUid(@PathVariable("uid") String uid) {
        if (StringUtils.isEmpty(uid))
            return Result.error(CodeMsg.ERROR_USER_UID_NOT_NULL);
        for (UserModel userModel : userModelList)
            if (userModel.getUid().equals(uid))
                return Result.success(userModel);
        return Result.error(CodeMsg.ERROR_USER_NOT_EXIST);
    }

}

測試

1、啓動

2、list

訪問：http://localhost:8080/user/list

{
    "code": 0,
    "msg": "Success",
    "data": [
        {
            "uid": "d8e2dfac-b6e8-46c7-9d43-5bb6bf99ce30",
            "name": "u0",
            "age": 10
        },
        {
            "uid": "87001637-9f21-4bc7-b589-bea1b2c795c4",
            "name": "u1",
            "age": 11
        },
        {
            "uid": "5e1398ca-8322-4a68-b0d2-1eb4c1cac9de",
            "name": "u2",
            "age": 12
        },
        {
            "uid": "e6ee5452-4148-4f6d-b820-9cc24e5c91b5",
            "name": "u3",
            "age": 13
        },
        {
            "uid": "3f428e26-57e1-4661-8275-ce3777b5da54",
            "name": "u4",
            "age": 14
        },
        {
            "uid": "b9d994b4-f090-40de-b0f3-e89c613061f2",
            "name": "u5",
            "age": 15
        },
        {
            "uid": "748d1349-5978-4746-b0c1-949eb5613a28",
            "name": "u6",
            "age": 16
        },
        {
            "uid": "abaadb7c-23fb-4297-a531-0c490927f6d5",
            "name": "u7",
            "age": 17
        },
        {
            "uid": "5e5917a1-8674-4367-94c6-6a3fd10a08d6",
            "name": "u8",
            "age": 18
        },
        {
            "uid": "03ed6a83-0cc0-4714-9d0d-f653ebb3a2eb",
            "name": "u9",
            "age": 19
        }
    ]
}

2、添加數據

看一下，數據是什麼樣子

與我們預想的結果一樣。

獲取數據

有數據樣式：

無數據樣式：

關於

馮文議。

2017年畢業於阿壩師範學院計算機應用專業。

現就職於深圳警聖技術股份有限公司，主要負責服務器接口開發工作。

技術方向：Java。

開源軟件：JavaLib。

後記

到這裏就結束了，如果在遇到什麼問題，或者有不明白的地方，可以通過評論、留言或者私信等方式，告訴我。

實戰：基於Spring Boot快速開發RESTful風格API接口

寫在前面的話

目標

假定

步驟

引入JavaLib

UserModel

編寫接口返回碼

BaseCodeMsg

編寫接口代碼

測試

獲取數據

關於

後記

Spring Cloud 部署時如何使用 Kubernetes 作爲註冊中心和配置中心

Spring Cloud OpenFeign調用流程

git stash 命令簡單使用

Redisson 分佈式鎖的正確使用

如何閱讀 Spring Cloud OpenFein 源碼

Spring Boot and RabbitMQ 初探

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結