Spring Boot 构建Rest服务实验手册(三)

在本系列的上一篇文章中, 给大家演示在Spring Boot中如何访问数据库，这次我们继续深入，规范 Restful 服务接口返回数据的格式。

返回数据格式设计

规范、统一额数据接口格式有利于服务端和客户端代码的重用，增强系统的可维护性。在实践中，对于 Restful 服务接口，通常建议采用如下的数据格式:

成功标志 (succ) - 定义本次调用在业务上是否成功，技术上是成功交由 HTTP 的返回值来决定。
(错误)返回代码 (code) - 通常在出现业务错误时使用，返回错误代码。
(错误)信息(msg) - 通常在出现业务错误时使用，返回经过本地化处理的错误消息，供客户端自己显示。
返回数据(data) - 正常调用时返回的数据，可以是简单的数据，也可以是复合的数据，比如对象，数组等。

基于以上的设计，在 Java 中的实现代码如下:

@Data
@Builder(toBuilder = true)
public class ApiResult {

    private boolean succ = false;
    private String code;
    private String msg;
    private Object data;

}

将这个类放入 api.vo 包中。该类使用了 @Data 注解来生成属性的 get/set 方法，使用 @Builder 来建立对应的构造函数。

改造新增待办接口

在原有的新增接口实现中，代码为:

@PostMapping("/todo")
public String addTodo(@RequestBody Todo todo) {

    todoBiz.addTodo(todo );

    return "ok";
}

要改统一的方式，需要改变函数的返回值为： ApiResult, 并根据 todoBiz.addTodo 的执行结果来赋予 ApiResult 的值。修改后的代码如下：

@PostMapping("/todo")
public ApiResult addTodo(@RequestBody Todo todo) {

    ApiResult.ApiResultBuilder builder = ApiResult.builder().succ(false).build().toBuilder();

    try {
        todoBiz.addTodo(todo);

        builder.succ(true);
    } catch(BizException e) {
        builder.msg(e.getMessage());
    }

    return builder.build();
}

这里，BizException 是一个自定义的异常类，继承于 RuntimeException, 注意: 第4行，第6行，第10行以后都是模板式的代码，可以总结为:

ApiResult.ApiResultBuilder builder = ApiResult.builder().succ(false).build().toBuilder();

try {

    /**
     * 实现业务逻辑，如果出错，抛出 BizException
     */

    builder.succ(true);
} catch(BizException e) {
    builder.msg(e.getMessage());
}

return builder.build();

我们给这个模板起个名字：Api 过程模板，后续的课程中，我们会教大家再把模板抽象出来以简化开发。

修改好以后，运行程序，用 PostMan 或是 curl 模拟发送 post 请求，body 参数设置为：

1	{"title":"task 1", "desc":"desc of task 1"}

服务端返回：

{
    "succ": true,
    "code": null,
    "msg": null,
    "data": null
}

说明执行成功了，在查看数据库，可以看到数据已经被插入到数据表中。

改造获取待办列表接口

在原有的 getTodoList 方法中，代码为:

@GetMapping("/todo")
public List<Todo> getTodoList() {

    List<Todo> todos = new ArrayList<>();
    todos.add(new Todo(1, "Call Metting", ""));
    todos.add(new Todo(2, "Print File", ""));

    return todos;
}

现在，我们改为由数据库中获取待办事项，并用 Api 过程模板来改造这个方法，

@GetMapping("/todo")
public ApiResult getTodoList() {

    ApiResult.ApiResultBuilder builder = ApiResult.builder().succ(false).build().toBuilder();

    try {
        List<Todo> list = todoBiz.listAll();
        builder.data(list).succ(true);
    } catch (BizException e) {
        builder.msg(e.getMessage());
    }

    return builder.build();
}

修改好以后，运行程序，从浏览器中直接访问 localhost:8080/todo , 结果为：

1	{"succ":true,"code":null,"msg":null,"data":[{"id":1,"title":"task 1","desc":"desc of task 1"}]}

下一步

在下一篇文章中，将介绍如何进行数据校验和错误处理。