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

在本系列的上一篇文章中, 给大家演示了如何构建一个简单的 Rest API。这次我们继续深入，为 Rest API 定义统一的输出格式。

返回数据格式设计

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

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

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

1. 在项目中增加名为: cn.com.hohistar.study.vertx.dto 的包。

2. 在包中新增名为: ApiResult 的类，该类用来统一（包装） API 的输出格式，代码如下:

@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResult<T> {

    private boolean succ;

    private String code;

    private String msg;

    private T data;

}

修改 Rest API

打开在 上一篇文章 中构建的 ApiVerticle 类，将以下代码:

router.route("/api/todo").handler(ctx -> {

    Todo todo = new Todo(1, "call tom", "description");
    ctx.response().end(todo.toString());

});

修改为:

router.route("/api/todo").handler(ctx -> {

    ApiResult<Todo> res = new ApiResult<>();
    res.setSucc(true);

    Todo todo = new Todo(1, "call tom", "description");

    res.setData(todo);

    ctx.response().end(JsonObject.mapFrom(res).toString());
});

可以看到，我们用新的 ApiResult 类包装了结果。

下一步

在下一篇文章中，将介绍如何如何访问关系数据库。