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

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

返回数据格式设计

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

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

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

1
2
3
4
5
6
7
8
9
10
@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 来建立对应的构造函数。

改造新增待办接口

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

1
2
3
4
5
6
7
@PostMapping("/todo")
public String addTodo(@RequestBody Todo todo) {

todoBiz.addTodo(todo );

return "ok";
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@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行以后都是模板式的代码,可以总结为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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"}

服务端返回:

1
2
3
4
5
6
{
"succ": true,
"code": null,
"msg": null,
"data": null
}

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

改造获取待办列表接口

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

1
2
3
4
5
6
7
8
9
@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 过程模板 来改造这个方法,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@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"}]}

下一步

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

本文标题:Spring Boot 构建Rest服务实验手册(三)

文章作者:晨星

发布时间:2019年07月15日 - 11:07

最后更新:2020年05月28日 - 16:05

原始链接:https://www.mls-tech.info/java/springboot-practice-manul-3/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。