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

格式选择

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

数据返回格式

package com.zhuma.demo.comm.result; import java.io.Serializable; import com.zhuma.demo.comm.enums.ResultCode; / * Created by zhumaer on 17/5/24. */ @Data public class Result implements Serializable { 
    private static final long serialVersionUID = -L; 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- */ 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(); } } 

★备注

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

写一个完整的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结果的封装。这其中貌似一个步骤也不能省略，但却导致我们写代码效率低下，其实最重要的一步仅仅是③，那么我们改如何改进呢？

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

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

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

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

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

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

结束语

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

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