共计 5490 个字符，预计需要花费 14 分钟才能阅读完成。
写在前面的话
这篇文章计划是在过年期间完成的，示例代码都写好了，结果亲戚来我家做客，文章没来得及写。已经很久没有更新文章了，小伙伴们，有没有想我啊。言归正传，下面开始，今天的话题。
目标
写一套符合规范，并且具有 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。
后记
到这里就结束了，如果在遇到什么问题，或者有不明白的地方，可以通过评论、留言或者私信等方式，告诉我。
