设计 API 接口 实现统一格式返回

返回格式

后端返回给前端我们一般用 JSON 体方式，定义如下：

{
	#返回状态码
	code:integer,		
	#返回信息描述
	message:string,
	#返回值
	data:object
}

CODE 状态码

code 返回状态码，一般小伙伴们是在开发的时候需要什么，就添加什么。

如接口要返回用户权限异常，我们加一个状态码为 101 吧，下一次又要加一个数据参数异常，就加一个 102 的状态码。这样虽然能够照常满足业务，但状态码太凌乱了

我们应该可以参考 HTTP 请求返回的状态码

：下面是常见的HTTP状态码：
200 - 请求成功
301 - 资源（网页等）被永久转移到其它URL
404 - 请求的资源（网页等）不存在
500 - 内部服务器错误

我们可以参考这样的设计，这样的好处就把错误类型归类到某个区间内，如果区间不够，可以设计成 4 位数。

#1000～1999 区间表示参数错误
#2000～2999 区间表示用户错误
#3000～3999 区间表示接口异常

这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据 message 相关的信息描述，可以快速定位。

Message

这个字段相对理解比较简单，就是发生错误时，如何友好的进行提示。一般的设计是和 code 状态码一起设计，如

package com.xxtsoft.enumeration;

/**
 * 状态码枚举
 * <p>
 * 常见的 http 状态码
 * 200 - 请求成功
 * 301 - 资源（网页等）被永久转移到其它URL
 * 404 - 请求的资源（网页等）不存在
 * 500 - 内部服务器错误
 * <p>
 * <p>
 * #1000～1999 区间表示参数错误
 * #2000～2999 区间表示用户错误
 * #3000～3999 区间表示接口异常
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 09:22
 */
public enum ResultCode {

    
    private Integer code;
    private String message;
    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }
}

再在枚举中定义，状态码

package com.xxtsoft.enumeration;

/**
 * 状态码枚举
 * <p>
 * 常见的 http 状态码
 * 200 - 请求成功
 * 301 - 资源（网页等）被永久转移到其它URL
 * 404 - 请求的资源（网页等）不存在
 * 500 - 内部服务器错误
 * <p>
 * <p>
 * #1000～1999 区间表示参数错误
 * #2000～2999 区间表示用户错误
 * #3000～3999 区间表示接口异常
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 09:22
 */
public enum ResultCode {

    /**
     * 成功状态码
     */
    SUCCESS(1, "成功"),

    /**
     * 参数错误 1001-1999
     */
    PARAM_IS_INVALID(1001, "参数无效"),
    /**
     * 参数错误 1001-1999
     */
    PARAM_IS_BLANK(1002, "参数为空"),
    /**
     * 参数错误 1001-1999
     */
    PARAM_TYPE_BIND_ERROR(1003, "参数类型错误"),
    /**
     * 参数错误 1001-1999
     */
    PARAM_NOT_COMPLETE(1004, "参数缺失"),

    /**
     * 用户错误 2001-2999
     */
    USER_NOT_LOGGED_IN(2001, "用户未登录,访问的路径需要验证,请登录"),

    /**
     * 用户错误 2001-2999
     */
    USER_L0GIN_ERROR(2002, "账号不存在或密码错误"),

    /**
     * 用户错误 2001-2999
     */
    USER_ACCOUNT_FORBIDDEN(2003, "账号已被禁用"),

    /**
     * 用户错误 2001-2999
     */
    USER_NOT_EXIST(2004, "用户不存在"),
    /**
     * 用户错误 2001-2999
     */
    USER_HAS_EXISTED(2005, "用户已存在"),
    /**
     * 服务器错误 没有此ID 3001
     */
    SERVER_NO_SUCH_ID(3001, "没有此ID");

    private Integer code;
    private String message;

    ResultCode() {
    }

    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer code() {
        return this.code;
    }

    public String message() {
        return this.message;
    }
}

状态码和信息就会一一对应，比较好维护。

Data

返回数据体，JSON 格式，根据不同的业务又不同的 JSON 体。

我们要设计一个返回体类 Result

package com.xxtsoft.entity;

import com.xxtsoft.enumeration.ResultCode;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.core.serializer.Serializer;

import java.io.Serializable;

/**
 * 返回体
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 09:43
 */
@Data
public class Result implements Serializable {
    private Integer code;
    private String message;
    private Object data;

    public Result(Integer code, String message, Object data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public Result() {
    }

    public Result(ResultCode resultCode, Object data) {
        this.code = resultCode.code();
        this.message = resultCode.message();
        this.data = data;
    }

    public Result(ResultCode resultCode) {
        this.code = resultCode.code();
        this.message = resultCode.message();
    }

    public Result(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    /**
     * 返回成功！
     *
     * @return 成功
     */
    public static Result success() {
        final Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        return result;
    }

    /**
     * 返回成功！
     *
     * @param data 数据
     * @return Result，成功！
     */
    public static Result success(Object data) {
        final Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        result.setData(data);
        return result;
    }

    /**
     * 返回失败！
     *
     * @param resultCode 失败枚举
     * @return 失败！
     */
    public static Result failure(ResultCode resultCode) {
        final Result result = new Result();
        result.setResultCode(resultCode);
        return result;
    }

    public static Result failure(Integer code, String msg, Object data) {
        return new Result(code, msg, data);
    }

    public static Result failure(Integer code, String msg) {
        return new Result(code, msg);
    }

    /**
     * 返回失败！
     *
     * @param resultCode 失败枚举
     * @param data       失败数据
     * @return 失败！
     */
    public static Result failure(ResultCode resultCode, Object data) {
        final Result result = new Result();
        result.setResultCode(resultCode);
        result.setData(data);
        return result;
    }


    public void setResultCode(ResultCode resultCode) {
        this.code = resultCode.code();
        this.message = resultCode.message();
    }


}

优雅优化

上面我们看到在 Result 类中增加了静态方法，使得业务处理代码简洁了。但小伙伴们有没有发现这样有几个问题：

1、每个方法的返回都是 Result 封装对象，没有业务含义

2、在业务代码中，成功的时候我们调用 Result.success，异常错误调用 Result.failure。是不是很多余

3、上面的代码，判断 id 是否为 null，其实我们可以使用 hibernate validate 做校验，没有必要在方法体中做判断。

我们最好的方式直接返回真实业务对象，最好不要改变之前的业务方式，如下图

@RestController
@RequestMapping("/RoleManagementController")
@Validated
@Slf4j
public class RoleManagementController {
   @Autowired
    private ISysUserRoleService iSysUserRoleService;
     /**
     * 根据 角色 id，获取拥有所有该角色的用户
     *
     * @param id 角色 id，角色 id 必须是数字，且大于 0
     * @return 所有用户
     */
    @GetMapping("/listUsersByRoleId/{id}")
    public List<SysUser> listUsersByRoleId(@DecimalMin(value = "0", message = "角色 id 必须是数字，且大于 0") @PathVariable("id") Integer id) {
        final List<SysUser> sysUsers = iSysUserRoleService.listUsersByRoleId(id);
        if (Validator.isNull(sysUsers) || CollUtil.isEmpty(sysUsers)) {
            throw new ResultException(ResultCode.SERVER_NO_SUCH_ID);
        }
        return sysUsers;
    }
}

实现方案

1、定义一个注解 @ResponseResult，表示这个接口返回的值需要包装一下

2、拦截请求，判断此请求是否需要被 @ResponseResult 注解

3、核心步骤就是实现接口 ResponseBodyAdvice 和 @ControllerAdvice，判断是否需要包装返回值，如果需要，就把 Controller 接口的返回值进行重写。

注解类

用来标记方法的返回值，是否需要包装

package com.xxtsoft.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.ElementType.*;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * 用来标记方法的返回值，是否需要包装
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 09:58
 */
@Retention(RUNTIME)
@Target({TYPE, METHOD})
@Documented
public @interface ResponseResult {
}

拦截器

拦截请求，是否此请求返回的值需要包装，其实就是运行的时候，解析 @ResponseResult 注解

package com.xxtsoft.interceptor;

import cn.hutool.core.lang.Console;
import com.xxtsoft.annotation.ResponseResult;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.lang.reflect.Method;

/**
 * 拦截器
 * 拦截请求，是否此请求返回的值需要包装，其实就是运行的时候，解析 @ResponseResult 注解
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 10:01
 */
@Slf4j
@Component
public class ResponseResultInterceptor implements HandlerInterceptor {
    /**
     * 标记名称
     */
    public static final String RESPONSE_RESULT_ANN = "RESPONSE-RESULT-ANN";

    /**
     * 此代码核心思想，就是获取此请求，是否需要返回值包装，设置一个属性标记。
     *
     * @param request  request
     * @param response response
     * @param handler  handler
     * @return 包装
     * @throws Exception 异常
     */
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        log.debug("进入 preHandle 方法");
        // 请求的方法
        if (handler instanceof HandlerMethod) {
            final HandlerMethod handlerMethod = (HandlerMethod) handler;
            final Class<?> beanType = handlerMethod.getBeanType();
            final Method method = handlerMethod.getMethod();
            //   判断是否在类对象上加了注解
            if (beanType.isAnnotationPresent(ResponseResult.class)) {
                // 设置此请求返回体，需要包装，往下传递，在 ResponseBodyAdvice 接口进行判断
                log.debug("此类有 ResponseResult 注解");
                request.setAttribute(RESPONSE_RESULT_ANN, beanType.getAnnotation(ResponseResult.class));
                // 方法上是否有注解
            } else if (method.isAnnotationPresent(ResponseResult.class)) {
                log.debug("此方法有 ResponseResult 注解");
                // 设置此请求返回体，需要包装，往下传递，在 ResponseBodyAdvice 接口进行判断
                request.setAttribute(RESPONSE_RESULT_ANN, method.getAnnotation(ResponseResult.class));
            }
        }
        return true;
    }
}

此代码核心思想，就是获取此请求，是否需要返回值包装，设置一个属性标记。

配置拦截器

package com.xxtsoft.config;

import com.xxtsoft.interceptor.ResponseResultInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * web 配置
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 11:13
 */
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private ResponseResultInterceptor responseResultInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 添加拦截器，配置拦截地址
        // 其中 /** 表示当前目录以及所有子目录（递归），/* 表示当前目录，不包括子目录。
        registry.addInterceptor(responseResultInterceptor).addPathPatterns("/**");
    }
}

重写返回体

package com.xxtsoft.handler;

import com.xxtsoft.annotation.ResponseResult;
import com.xxtsoft.entity.Result;
import com.xxtsoft.exception.ResultException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import javax.servlet.http.HttpServletRequest;

/**
 * 重写返回体
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 10:08
 */
@Slf4j
@ControllerAdvice
public class ResponseResultHandler implements ResponseBodyAdvice<Object> {
    /**
     * 标记名称
     */
    public static final String RESPONSE_RESULT_ANN = "RESPONSE-RESULT-ANN";

    /**
     * 是否请求 包含了 包装注解标记
     * ，没有就直接返回，不需要重写返回体
     *
     * @param returnType    returnType
     * @param converterType converterType
     * @return boolean
     */
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        log.debug("进入 supports 方法");
        final ServletRequestAttributes sra = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        assert sra != null;
        final HttpServletRequest request = sra.getRequest();
        // 判断请求是否有包装标记
        final ResponseResult responseResultAnn = (ResponseResult) request.getAttribute(RESPONSE_RESULT_ANN);
        return responseResultAnn != null;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        log.debug("进入 返回体，重写格式 ，处理中！！！body {}", body);
        if (body instanceof Result) {
            // 是 Result 包转好的，说明是处理过异常的，直接返回
            return body;
        }
        return Result.success(body);


    }
}

上面代码就是判断是否需要返回值包装，如果需要就直接包装。

异常类

package com.xxtsoft.exception;

import com.xxtsoft.enumeration.ResultCode;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * 返回体 异常类
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 10:25
 */
@EqualsAndHashCode(callSuper = true)
@Data
public class ResultException extends RuntimeException {
    private Integer code;
    private String message;
    private Object data;

    public ResultException(ResultCode resultCode) {
        this.code = resultCode.code();
        this.message = resultCode.message();
    }

    public ResultException(ResultCode resultCode, Object data) {
        this.code = resultCode.code();
        this.message = resultCode.message();
        this.data = data;
    }
}

全局异常处理

package com.xxtsoft.controller;

import com.xxtsoft.entity.ResponseJson;
import com.xxtsoft.entity.Result;
import com.xxtsoft.enumeration.ResultCode;
import com.xxtsoft.exception.ResultException;
import com.xxtsoft.exception.SysDeptException;
import com.xxtsoft.exception.SysRoleException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import javax.validation.ValidationException;

/**
 * 系统级别的异常处理
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-18 10:55
 */
@RestControllerAdvice
@Slf4j
public class SystemExceptionHandler {
    /**
     * 捕获
     * ResultException
     *
     * @param exception ResultException
     * @return 对应的信息
     */
    @ExceptionHandler(value = {ResultException.class})
    public Result sysDeptException(ResultException exception) {
        log.debug("code {},message {},data {} ", exception.getCode(), exception.getMessage(), exception.getData());
        return Result.failure(exception.getCode(), exception.getMessage(), exception.getData());
    }

    /**
     * 处理 参数不合法异常
     *
     * @param validator ValidationException
     * @return Result
     */
    @ExceptionHandler(value = {ValidationException.class})
    public Result validationException(Exception validator) {
        log.debug("{}", validator.toString());
        return Result.failure(ResultCode.PARAM_IS_INVALID, validator.getMessage());
    }
}

重写 Controller

package com.xxtsoft.controller.system.management;

import cn.hutool.core.collection.CollUtil;
import cn.hutool.core.lang.Validator;
import cn.hutool.core.lang.tree.Tree;
import com.xxtsoft.annotation.ResponseResult;
import com.xxtsoft.entity.*;
import com.xxtsoft.enumeration.ResultCode;
import com.xxtsoft.exception.ResultException;
import com.xxtsoft.exception.SysDeptException;
import com.xxtsoft.exception.SysRoleException;
import com.xxtsoft.service.*;
import lombok.extern.slf4j.Slf4j;
import org.apache.ibatis.annotations.Delete;
import org.hibernate.validator.constraints.Length;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.validation.constraints.DecimalMin;
import javax.validation.constraints.NotBlank;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;

/**
 * 角色管理控制器
 * <p>
 * 获取权限树
 * <p>
 * 获取所有角色
 * <p>
 * 添加角色
 * 删除角色
 *
 * @author yang
 * @version 1.0.0
 * @date 2020-11-10 10:03
 */
@RestController
@RequestMapping("/RoleManagementController")
@Validated
@Slf4j
public class RoleManagementController {

    @Autowired
    private ISysMenuService iSysMenuService;

    @Autowired
    private ISysUserService iSysUserService;

    @Autowired
    private ISysRoleService iSysRoleService;

    @Autowired
    private ISysRoleFunctionService iSysRoleFunctionService;

    @Autowired
    private ISysUserRoleService iSysUserRoleService;


    /**
     * 获取 菜单树
     *
     * @return 菜单树
     */
    @PostMapping("/treeList")
    public ResponseJson treeList() {
        final List<Tree<Integer>> trees = iSysMenuService.treeList();
        log.debug("trees {}", trees);
        return new ResponseJson().ok(trees).message("获取成功");
    }

    /**
     * 获取 所有的角色
     *
     * @return 所有的角色
     */
    @GetMapping("/roleList")
    public ResponseJson roleListResponseJson() {
        final List<SysRole> sysRoleList = iSysRoleService.list();
        log.debug("{}", sysRoleList);
        return new ResponseJson().ok(sysRoleList).message("获取成功");
    }

    /**
     * 根据 角色 id 获取对应的 （功能）权限
     *
     * @param id 角色 id
     * @return 功能（权限）
     */
    @GetMapping("/listFunctionByRoleId/{id}")
    public ResponseJson getJurisdiction(@DecimalMin(value = "0", message = "角色 id 必须是数字，且大于 0") @PathVariable("id") Integer id) {
        final List<SysFunction> sysFunctionList = iSysRoleFunctionService.listFunctionByRoleId(id);
        log.debug("id {},list {}", id, sysFunctionList);
        if (Validator.isNull(sysFunctionList) || CollUtil.isEmpty(sysFunctionList)) {
            throw new SysRoleException("没有此 id");
        }
        return new ResponseJson().ok(sysFunctionList).message("获取成功");
    }

    /**
     * 根据 角色 id，获取拥有所有该角色的用户
     *
     * @param id 角色 id，角色 id 必须是数字，且大于 0
     * @return 所有用户
     */
    @ResponseResult
    @GetMapping("/listUsersByRoleId/{id}")
    public List<SysUser> listUsersByRoleId(@DecimalMin(value = "0", message = "角色 id 必须是数字，且大于 0") @PathVariable("id") Integer id) {
        final List<SysUser> sysUsers = iSysUserRoleService.listUsersByRoleId(id);
        if (Validator.isNull(sysUsers) || CollUtil.isEmpty(sysUsers)) {
            throw new ResultException(ResultCode.SERVER_NO_SUCH_ID);
        }
        return sysUsers;
    }


    /**
     * 根据 角色 id 和 用户 ID 取消一条权限
     *
     * @param role 角色 id
     * @param user 用户 ID
     * @return 是否取成功
     */
    @ResponseResult
    @DeleteMapping("/cancelRoleByRoleIdAndUserId/{role}/{user}")
    public Boolean cancelRoleByRoleIdAndUserId(@DecimalMin(value = "0", message = "角色 id 必须是数字，且大于 0") @PathVariable("role") Integer role, @DecimalMin(value = "0", message = "用户 id 必须是数字，且大于 0") @PathVariable("user") Integer user) {
        log.debug(" role {},user {}", role, user);
        return iSysUserRoleService.cancelRoleByRoleIdAndUserId(role, user);
    }

    /**
     * 根据 角色 id
     * 删除一个角色
     *
     * @param roleId 角色 id
     * @return 是否成功！
     */
    @ResponseResult
    @DeleteMapping("/delRoleByRoleId/{roleId}")
    public Boolean delRoleByRoleId(@PathVariable("roleId") Integer roleId) {
        log.debug("roleId {}", roleId);
        // 删除一个角色
        final boolean b = iSysRoleService.removeById(roleId);
        // 根据 角色 去 角色功能表 删除角色对应的功能
        iSysRoleFunctionService.deleteByRoleId(roleId);
        return b;
    }

    /**
     * 添加一个角色
     *
     * @param roleName 角色名
     * @param roleDes  角色描述
     * @return 添加成功后的角色
     */
    @ResponseResult
    @PutMapping("/addRole/{roleName}/{roleDes}")
    public Boolean addRole(@NotBlank(message = "角色名称不能为空")
                           @Length(max = 50, min = 1, message = "角色名称长度限制 1 ~ 50") @PathVariable String roleName, @NotBlank(message = "角色描述不能为空")
                           @Length(max = 50, min = 1, message = "角色描述长度限制 1 ~ 50") @PathVariable String roleDes) {
        log.debug(" 角色名称 {} 角色描述 {}", roleName, roleDes);


        final SysRole sysRole = SysRole.builder()
                .froleName(roleName)
                .froleDesc(roleDes)
                .fcreateLn(iSysUserService.getLoginUserName())
                .fcreateDate(LocalDateTime.now())
                .flastModifyLn(iSysUserService.getLoginUserName())
                .flastModifyDate(LocalDateTime.now())
                .fversion(LocalDate.now())
                .build();

        return iSysRoleService.save(sysRole);

    }

    /**
     * 根据角色 id 变更权限
     *
     * @param roleId       角色 id
     * @param functionList 权限 数组
     * @return 是否成功
     */
    @ResponseResult
    @PutMapping("/AddPermissionByRoleId/{roleId}")
    public boolean addPermissionByRoleId(@PathVariable("roleId") Integer roleId, @RequestBody List<Integer> functionList) {
        log.debug(" roleId {}, functions {}", roleId, functionList);
        return iSysRoleFunctionService.addPermissionByRoleId(roleId, functionList);
    }

}

在控制器类上或者方法体上加上 @ResponseResult 注解，这样就 ok 了，简单吧。到此返回的设计思路完成，是不是又简洁，又优雅。

总结

这个方案还有没有别的优化空间，当然是有的。如：每次请求都要反射一下，获取请求的方法是否需要包装，其实可以做个缓存，不需要每次都需要解析。