代码简洁之道：统一返回格式 -- 2022-08-31

发表于 | 分类于

其实很多时候, 写代码更像是在创造艺术。 —— 指北君

今天指北君说一个让代码变得更整洁的小技巧。

0. 前言

目前很多项目都是前后端分离，前后端会事先约定好返回格式。那么后端如何做，才能优雅的返回统一格式呢，接下来，我会带着你一步步实现。

1. 直接返回结果

先看一下最基本的例子，直接将结果原封不动返回：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Data
@AllArgsConstructor
@JsonIgnoreProperties(ignoreUnknown = true)
public class TestVo {

    private static final long serialVersionUID = 1L;

    @Schema(name = "姓名")
    private String name;

    @Schema(name = "年龄")
    private Integer age;

}

1
2
3
4
5
6
7
8
9
10
@RestController
@RequestMapping(value = "/test")
public class TestApi {

    @GetMapping("/simple")
    public TestVo simple() {
        TestVo testVo = new TestVo("张三", 30);
        return testVo;
    }
}

返回结果：

1
2
3
4
{
    "name": "张三",
    "age": 30
}

2. 约定返回格式

假如已经与前端开发妹子约定好了格式，比如：

1
2
3
4
5
{
    "code": 0,
    "msg": "错误信息",
    "data": 实际返回结果
}

那么我们首先需要编写一个封装结果类Result。为了方便封装，在这个类中增加一个success方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 返回编码
     */
    private Integer code;

    /**
     * 编码描述
     */
    private String msg;

    /**
     * 业务数据
     */
    private T data;

    /**
     * 返回成功结果对象
     *
     * @param data
     * @param <T>
     * @return
     */
    public static <T> Result<T> success(T data) {
        Result result = new Result();
        result.setCode(0);
        result.setMsg("success");
        result.setData(data);
        return result;
    }
}

3. 返回统一格式结果

后台接口代码微调一下，返回值改为Result，泛型为原返回值的类型：

1
2
3
4
5
6
7
8
9
10
@RestController
@RequestMapping(value = "/test")
public class TestApi {

    @GetMapping("/withResult")
    public Result<TestVo> withResult() {
        TestVo testVo = new TestVo("张三", 30);
        return Result.success(testVo);
    }
}

返回结果：

1
2
3
4
5
6
7
8
{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "张三",
        "age": 30
    }
}

至此，返回结果完美符合格式。

但是这样的代码并不算整洁：每个接口的返回值都必须是Result<>，并且return的时候都要用Result.success()方法封装一下。

那么，有没有更优雅的方法？我们继续往下看：

4. 切片封装统一格式

  1. 编写注解

    实际使用场景中，并不是所有接口都需要统一格式。我们这里使用一个注解作为开关，按需控制接口返回格式。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    @Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiResult {
 String value() default "";

 int successCode() default 0;

 String successMsg() default "success";

 Class<? extends IResult> resultClass() default Result.class;
}
  2. 编写ControllerAdvice

    ```java @ControllerAdvice public class MyResponseBodyAdvice implements ResponseBodyAdvice {

    protected boolean isStringConverter(Class converterType) { return converterType.equals(StringHttpMessageConverter.class); }

    protected boolean isApiResult(MethodParameter returnType) { return returnType.hasMethodAnnotation(ApiResult.class); }

    @Override public boolean supports(MethodParameter returnType, Class converterType) { return !isStringConverter(converterType) && isApiResult(returnType); }

    @Override public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) { //关键
    return Result.success(body); }

}

1
2
3
4
5
6
7
8
9
10
这里有一点要**注意**，这个advice中supports方法中判断返回结果类型必须为非String类型。如果返回结果为String类型，那么result要转为json字符串后再返回，需要再写一个advice。

3. ##### 见证奇迹的时刻到了
```java
@ApiResult
@GetMapping("/withResultHide")
public TestVo withResultHide() {
    TestVo testVo = new TestVo("张三", 30);
    return testVo;
}

这段代码与最开始一样，并没有返回Result，仅仅加上了@ApiResult注解，我们看返回结果：

1
2
3
4
5
6
7
8
{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "张三",
        "age": 30
    }
}

大功告成！

以上只是最精简的例子，实际使用中还结合了 统一异常封装、自定义返回格式 等功能。我们注意到@ApiResult注解中，有三个参数：successCode、successMsg、resultClass，就是为了自定义返回格式预留的，下面再看两个场景：

5. 自定义返回格式

##### 场景1：返回成功时code为200 如果个别接口的返回格式与默认格式相同，但是要求code等于200时才代表成功，那么修改下successCode参数即可：

1
2
3
4
5
6
@ApiResult(successCode = 200, successMsg = "ok")
@GetMapping("/withResultHide")
public TestVo withResultHide() {
    TestVo testVo = new TestVo("张三", 30);
    return testVo;
}

返回成功时，结果中的code和msg都变为设置的值：

1
2
3
4
5
6
7
8
{
    "code": 200,
    "msg": "ok",
    "data": {
        "name": "张三",
        "age": 30
    }
}

##### 场景2：自定义返回格式 如果某个接口的返回格式不是默认的返回格式，比如约定返回returnCode、returnDesc、data（对应默认的code、msg、data）。那么则需要新增一个返回结果类，比如ReturnResult：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class ReturnResult<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 返回编码
     */
    private String returnCode;

    /**
     * 编码描述
     */
    private String returnDesc;

    /**
     * 业务数据
     */
    private T data;

    /**
     * 返回成功结果对象
     *
     * @param data
     * @param <T>
     * @return
     */
    public static <T> ReturnResult<T> success(T data) {
        ReturnResult result = new ReturnResult();
        result.setReturnCode(0);
        result.setReturnDesc("success");
        result.setData(data);
        return result;
    }
}

然后修改接口上的@ApiResult注解中的resultClass属性

1
2
3
4
5
6
@ApiResult(resultClass = ReturnResult.class)
@GetMapping("/withResultHide")
public TestVo withResultHide() {
    TestVo testVo = new TestVo("张三", 30);
    return testVo;
}

这时，返回结果就变为想要的格式了：

1
2
3
4
5
6
7
8
{
    "returnCode": "0",
    "returnDesc": "success",
    "data": {
        "name": "张三",
        "age": 30
    }
}

小结

只要按照上面一步步改造，即可实现统一返回结果，既简洁、又优雅。还等什么，搞起来吧~

写在最后

欢迎加入Java技术指北读者交流群，聊天学习摸鱼为主，不定时会分享一些技术要点和优质学习资源，有一群有趣有料的小伙伴在等你哦！进群方式：公众号后台回复888，按提示操作即可进群。

Java Geek Tech wechat
欢迎订阅 Java 技术指北，这里分享关于 Java 的一切。