实战：基于Spring Boot快速开发RESTful风格API接口

客官°小女子只卖身不卖艺 2022-03-07 01:48 838阅读 0赞

## 写在前面的话 ##

这篇文章计划是在过年期间完成的，示例代码都写好了，结果亲戚来我家做客，文章没来得及写。已经很久没有更新文章了，小伙伴们，有没有想我啊。言归正传，下面开始，今天的话题。

## 目标 ##

写一套符合规范，并且具有RESTful风格的API接口。

## 假定 ##

*  你已会使用Spring Boot 2.x。
 *  你已会使用Gradle构建Spring Boot工程。
 *  你已会基于Spring Boot编写API接口。
 *  你已会使用接口调试工具。

如果你还不会使用Spring Boot写接口，建议先看一下这篇文章 ：

[用Spring Boot开发API接口][Spring Boot_API]

## 步骤 ##

1、基于Gradle构建Spring Boot示例项目。

2、引入JavaLib。

3、编写接口代码。

4、测试接口。

## 引入JavaLib ##

测试版(SNAPSHOT)，都会发布到 **[JitPack][]** 上，所以，从这里拉取的，都会是最新的，但是需要配置仓库地址。

正式版(RELEASE)，才会推送到 **[Maven中央][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"));
        }

测试结果：

![Test Param Error][]

## 编写接口代码 ##

接下来，开始编写我们的接口代码。

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

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、启动

![启动项目][Test Param Error]

2、list

访问：[http://localhost][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、添加数据

![添加数据][Test Param Error]

看一下，数据是什么样子

![添加数据][Test Param Error]

与我们预想的结果一样。

## 获取数据 ##

有数据样式：

![有数据][Test Param Error]

无数据样式：

![无数据][Test Param Error]

## 关于 ##

冯文议。

2017年毕业于阿坝师范学院计算机应用专业。

现就职于深圳警圣技术股份有限公司，主要负责服务器接口开发工作。

技术方向：Java。

开源软件：JavaLib。

## 后记 ##

到这里就结束了，如果在遇到什么问题，或者有不明白的地方，可以通过评论、留言或者私信等方式，告诉我。

[Spring Boot_API]: https://blog.csdn.net/qq_28336351/article/details/79327357
[JitPack]: https://jitpack.io/#fengwenyi/JavaLib
[Maven]: https://search.maven.org/search?q=g:com.fengwenyi%20AND%20a:JavaLib&core=gav
[JavaLib]: https://github.com/fengwenyi/JavaLib
[Test Param Error]: https://cdn.segmentfault.com/v-5c8b4d77/global/img/squares.svg
[http_localhost]: http://localhost