Restful Api写法心得之三《返回值篇》

来源：互联网发布：mac版的rar 解压软件编辑：程序博客网时间：2024/06/16 08:18

前言
温馨提示：可以订阅我的微信公众号，在手机里看技术文档也很不错哦o(￣︶￣)o！

这是关于api基础写法的第三篇文章了，这里给下前两篇连接
《路径定义篇》《参数接收篇》，对于本篇文章我们主要说下接口的数据返回值的问题。

格式选择

返回格式目前主流的应该只有XML、JSON两种吧，这里我们不做对比，我们使用JSON作为接口的返回格式。

数据返回格式

数据的返回格式其实是个比较纠结的问题，在restful风格中很多文章都讲解使用的是http状态码控制请求的结果状态，例如：http状态码为200~300的时候，为正常状态，response响应体即为所需要返回的数据，404时代表没有查询到数据，响应体即为空，500为系统错误，响应体也为空等等，但是这种方式也是存在很大问题的，一是http状态码是有限的，而且每个状态码都已经被赋予特殊的含义，在企业开发中当接口遇到错误的时候，我们可能更希望将结果状态码标记的更为详细，更利于前端开发者使用，毕竟写接口的目的也是方便前端使用，这样也可以降低前后端开发人员沟通成本。
下面给出我们在实际开发中使用的返回值统一格式：

package com.zhuma.demo.comm.result;import java.io.Serializable;import com.zhuma.demo.comm.enums.ResultCode;/** * Created by zhumaer on 17/5/24. */ @Datapublic class Result implements Serializable {    private static final long serialVersionUID = -3948389268046368059L;    private Integer code;    private String msg;    private Object data;    public Result() {}    public Result(Integer code, String msg) {        this.code = code;        this.msg = msg;    }    public static Result success() {        Result result = new Result();        result.setResultCode(ResultCode.SUCCESS);        return result;    }    public static Result success(Object data) {        Result result = new Result();        result.setResultCode(ResultCode.SUCCESS);        result.setData(data);        return result;    }    public static Result failure(ResultCode resultCode) {        Result result = new Result();        result.setResultCode(resultCode);        return result;    }    public static Result failure(ResultCode resultCode, Object data) {        Result result = new Result();        result.setResultCode(resultCode);        result.setData(data);        return result;    }    public void setResultCode(ResultCode code) {        this.code = code.code();        this.msg = code.message();    }}

备注

上面代码我们注意到其中引入了一个ResultCode枚举类，该类也是我们后面紧接着要说的，全局统一返回状态码。
这里说明下字段data不是在code=1为成功的时候才会有值哦，比如当code为参数无效错误时，data可以放入更详细的错误描述，用于指明具体是哪个参数为什么导致的无效的。

全局状态码

当你发现你的系统中错误码随意定义，没有任何规范的时候，你应该考虑下使用一个枚举全局管理下你的状态码，这对线上环境定位错误问题和后续接口文档的维护都是很有帮助的。
下面我们在给出一个完整版代码示例，用于参考：

package com.zhuma.demo.comm.enums;import java.util.ArrayList;import java.util.List;/** * API 统一返回状态码 * Created by zhumaer on 17/5/24. */public enum ResultCode {    /* 成功状态码 */    SUCCESS(1, "成功"),    /* 参数错误：10001-19999 */    PARAM_IS_INVALID(10001, "参数无效"),    PARAM_IS_BLANK(10002, "参数为空"),    PARAM_TYPE_BIND_ERROR(10003, "参数类型错误"),    PARAM_NOT_COMPLETE(10004, "参数缺失"),    /* 用户错误：20001-29999*/    USER_NOT_LOGGED_IN(20001, "用户未登录"),    USER_LOGIN_ERROR(20002, "账号不存在或密码错误"),    USER_ACCOUNT_FORBIDDEN(20003, "账号已被禁用"),    USER_NOT_EXIST(20004, "用户不存在"),    USER_HAS_EXISTED(20005, "用户已存在"),    /* 业务错误：30001-39999 */    SPECIFIED_QUESTIONED_USER_NOT_EXIST(30001, "某业务出现问题"),    /* 系统错误：40001-49999 */    SYSTEM_INNER_ERROR(40001, "系统繁忙，请稍后重试"),    /* 数据错误：50001-599999 */    RESULE_DATA_NONE(50001, "数据未找到"),    DATA_IS_WRONG(50002, "数据有误"),    DATA_ALREADY_EXISTED(50003, "数据已存在"),    /* 接口错误：60001-69999 */    INTERFACE_INNER_INVOKE_ERROR(60001, "内部系统接口调用异常"),    INTERFACE_OUTTER_INVOKE_ERROR(60002, "外部系统接口调用异常"),    INTERFACE_FORBID_VISIT(60003, "该接口禁止访问"),    INTERFACE_ADDRESS_INVALID(60004, "接口地址无效"),    INTERFACE_REQUEST_TIMEOUT(60005, "接口请求超时"),    INTERFACE_EXCEED_LOAD(60006, "接口负载过高"),    /* 权限错误：70001-79999 */    PERMISSION_NO_ACCESS(70001, "无访问权限");    private Integer code;    private String message;    ResultCode(Integer code, String message) {        this.code = code;        this.message = message;    }    public Integer code() {        return this.code;    }    public String message() {        return this.message;    }    public static String getMessage(String name) {        for (ResultCode item : ResultCode.values()) {            if (item.name().equals(name)) {                return item.message;            }        }        return name;    }    public static Integer getCode(String name) {        for (ResultCode item : ResultCode.values()) {            if (item.name().equals(name)) {                return item.code;            }        }        return null;    }    @Override    public String toString() {        return this.name();    }    //校验重复的code值    public static void main(String[] args) {        ResultCode[] ApiResultCodes = ResultCode.values();        List<Integer> codeList = new ArrayList<Integer>();        for (ResultCode ApiResultCode : ApiResultCodes) {            if (codeList.contains(ApiResultCode.code)) {                System.out.println(ApiResultCode.code);            } else {                codeList.add(ApiResultCode.code());            }        }    }}

★备注

上述例子中我们对状态码做了一个大的类型上的划分，在实际开发中你可以在后面写你更加详细的错误状态

写一个完整的Controller

那我们已查询、更新用户为例，看看现在我们写一个完整的controller都需要做什么呢？

@RestController@RequestMapping("/users")public class UserController {    private static final Logger LOGGER = LoggerFactory.getLogger(UserController.class);    private final UserService userService;    @Autowired    public UserController(UserService userService) {        this.userService = userService;    }    @GetMapping("/{userId}")    Result getUser(@PathVariable("userId") Long userId) {        User user = userService.getUserById(userId);        return Result.success(user);    }    @PutMapping("/{userId}")    public Result updateUser(@PathVariable("userId") Long userId, @RequestBody User user) {        LOGGER.info("Call updateUser start, params:{}", JsonUtil.object2Json(user));//注意此处打印日志有不合理的地方，user里可能带有pwd密码等明文敏感信息，需要做过滤打印。        Result result = new Result();        //参数校验        if (user.getId() == null || user.getName == null) {            result.setResultCode(ResultCode.PARAM_IS_INVALID);            LOGGER.info("Call updateUser end, result:{}", JsonUtil.object2Json(result));            return result;        }        try {            //更新数据            User dbUser = userService.getUserById(user.getId());            if (dbUser == null) {                result.setResultCode(ResultCode.USER_NOT_EXIST);            } else {                User updatedUser = userService.updateDbAndCache(user);                result.setData(updatedUser);                result.setResultCode(ResultCode.SUCCESS);            }        } catch (Exception e) {            LOGGER.info("Call updateUser occurs exception, caused by: ", e);            result.setResultCode(ResultCode.SYSTEM_INNER_ERROR);        }        LOGGER.info("Call updateUser end, result:{}", JsonUtil.object2Json(result));        return result;    }}

我们看下上面的例子，这似乎已经可以满足对用户管理操作的需求，但是对于一个查询用户方法来讲代码量还是可以接受的，但是对于一个简单的更新用户操作，我们却写了一大堆的逻辑，其中包括：① 请求参数、响应结果日志打印 ② 基础参数的校验 ③更新用户业务主逻辑 ④ 全局异常的捕获 ⑤ 对Result结果的封装。这其中貌似一个步骤也不能省略，但却导致我们写代码效率低下，其实最重要的一步仅仅是③，那么我们改如何改进呢？

① 请求参数、响应结果日志打印 -> 使用在controller方法外对做切面统一打印日志（非GET方法都会打印）
② 基础参数的校验 -> 使用hibernate validate做操作校验
④ 全局异常的捕获 -> 使用@ControllerAdvice写全局异常处理类控制异常展现方式
⑤ 对Result结果的封装 -> 实现ResponseBodyAdvice接口，对接口响应体统一处理

上面我们只是提供的一个解决问题的思路，但是还没有实际的代码，后面的文章中我们会依次给出解决方案。
解决方案(逐步更新中……)：
①请求参数、响应结果日志打印 -> 企业实战之切面编程《统一打印日志》
②基础参数的校验 -> 企业实战之Spring项目《参数校验》
③全局异常的捕获 -> 企业实战之spring增强器实现《全局异常处理器》
最后我们期望着写controller方法变为：

@PutMapping("/{userId}")public User updateUser(@PathVariable("userId") Long userId, @Valid @RequestBody User user) {    //更新数据    User dbUser = userService.getUserById(user.getId());    if (dbUser == null) {        throw new BusinessException(ResultCode.USER_NOT_EXIST);    }    return userService.updateDbAndCache(user);}

无效数据不返回，必要数据返回

什么叫无效数据不返回，必要数据返回呢？

无效数据清理：对于json响应接口，我们需要遵守对所有值为null的字段不做返回，对前端不关心的数据不做返回（合理的定义VO是很有必要的）。
对于spring boot 我们可以用下配置，实现字段值为null时不做返回。

spring.jackson.date-format=yyyy-MM-dd HH:mm:ssspring.jackson.time-zone=Asia/Shanghaispring.jackson.default-property-inclusion= non_null

必要数据返回：对于添加（POST）、修改（PUT | PATCH）这类方法我们需要立即返回添加或更新后的数据以备前端使用（这是一个约定需要遵守）。

结束语

resetful api写法基础知识写到这里我们先告一段落，后面我们主要介绍拦截器如何应用到企业实战中，欢迎你继续阅读O(∩_∩)O哈哈~。

欢迎关注我们的公众号或加群，等你哦！

阅读全文

1 0