代码简洁之道：统一返回格式

迈不过友情╰ 2024-04-07 11:18 64阅读 0赞

#### 1. 前言 ####

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

#### 2. 直接返回结果 ####

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

@Data
    @AllArgsConstructor
    @JsonIgnoreProperties(ignoreUnknown = true)
    public class TestVo {
    
        private static final long serialVersionUID = 1L;
    
        @Schema(name = "姓名")
        private String name;
    
        @Schema(name = "年龄")
        private Integer age;
    
    }

@RestController
    @RequestMapping(value = "/test")
    public class TestApi {
    
        @GetMapping("/simple")
        public TestVo simple() {
            TestVo testVo = new TestVo("张三", 30);
            return testVo;
        }
    }

返回结果：

{
        "name": "张三",
        "age": 30
    }

#### 3. 约定返回格式 ####

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

{
        "code": 0,
        "msg": "错误信息",
        "data": 实际返回结果
    }

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

@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;
        }
    }

#### 4. 返回统一格式结果 ####

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

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

返回结果：

{
        "code": 0,
        "msg": "success",
        "data": {
            "name": "张三",
            "age": 30
        }
    }

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

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

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

#### 5. 切片封装统一格式 ####

编写注解

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

@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;
    }

编写ControllerAdvice

@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);
        }
    
    }

这里有一点要注意，这个advice中supports方法中判断返回结果类型必须为非String类型。如果返回结果为String类型，那么result要转为json字符串后再返回，需要再写一个advice。

见证奇迹的时刻到了

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

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

{
        "code": 0,
        "msg": "success",
        "data": {
            "name": "张三",
            "age": 30
        }
    }

大功告成！

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

#### 6. 自定义返回格式 ####

场景1：返回成功时code为200

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

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

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

{
        "code": 200,
        "msg": "ok",
        "data": {
            "name": "张三",
            "age": 30
        }
    }

场景2：自定义返回格式

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

@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属性：

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

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

{
        "returnCode": "0",
        "returnDesc": "success",
        "data": {
            "name": "张三",
            "age": 30
        }
    }

#### 小结 ####

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