设计之道－controller层的设计

2018-09-01 本文已影响27人 SawyerZhou

最近想把平时工作中总结出来的一些技巧和最佳实践分享给大家，主要包含java编程和数据库设计，本篇着重于web应用开发中controller层的实践。

在讲controller层的设计之前，我想先简单讲讲web应用的工程结构。一般来说，我们的web工程结构会分为三层，自下而上是dao层，service层和controller层。

dao层是数据层，直接进行数据库的读写操作，返回数据对象DO，DO与数据库表一一对应。
service层为业务层，用来实现业务逻辑。能调用dao层或者service层，返回数据对象DO或者业务对象BO，BO通常由DO转化、整合而来，可以包含多个DO的属性，也可以是只包含一个DO的部分属性。通常为了简便，如果无需转化，service也可以直接返回DO。外部调用（HTTP、RPC）方法也在这一层，对于外部调用来说，service一般会将外部调用返回的DTO转化为BO。
controller层为控制层，主要处理外部请求。调用service层，将service层返回的BO/DO转化为DTO/VO并封装成统一返回对象返回给调用方。如果返回数据用于前端模版渲染则返回VO，否则一般返回DTO。不论是DTO还是VO，一般都会对BO/DO中的数据进行一些转化和整合，比如将gender属性中的0转化“男”，1转化为“女”等。

java工程结构.jpg

了解了工程结构后，我们可以来讲讲controller层的设计。首先明确一点，除了极少数不复用的简单处理，controller层不应该包含业务逻辑，controller的功能应该有以下五点：
1.参数校验
2.调用service层接口实现业务逻辑
3.转换业务／数据对象
4.组装返回对象
5.异常处理

我会拿一个简单的业务操作：变更用户信息并且返回更新后的用户信息作为例子，来介绍一下controller层的设计理念。

下面是一个最普通的写法，这里已经将更新并返回用户信息的业务逻辑全放在了service层，但是controller层仍需要承担参数校验、转换对象、组装返回对象和异常处理的工作：

/**
 * @Author: Sawyer
 * @Description:
 * @Date: Created in 下午5:43 18/9/1
 */
@RestController
@RequestMapping("/v1/user")
public class UserController {

@Autowired
UserService userService;

@PutMapping("/{id}")
public HttpResult<UserDTO> updateUser(@PathVariable("id") Integer id, @RequestBody UserDTO userDTO) {
    HttpResult<UserDTO> result = new HttpResult<>();
    //参数校验，UserDTO.name不能为空
    if (userDTO.getName() == null) {
        result.setSuccess(false);
        result.setCode(ResultCode.INVALID_PARAM.getCode());
        result.setMessage("name不能为空");
    } else {
        //调用service更新user，更新可能抛出异常，要捕获
        try {
            User updatedUser = userService.updateUser(id, userDTO);
            //转换对象，转化DO为DTO
            UserDTO updatedDto = new UserDTO();
            BeanUtils.copyProperties(updatedUser, updatedDto);
            if (GenderEnum.MALE.getCode() == updatedUser.getGender()) {
                updatedDto.setGenderDesc(GenderEnum.MALE.name());
            } else {
                updatedDto.setGenderDesc(GenderEnum.FEMALE.name());
            }
            //组装返回对象
            result.setData(updatedDto);
            result.setSuccess(true);
            result.setCode(ResultCode.SUCCESS.getCode());
            result.setMessage(ResultCode.SUCCESS.getMessage());
        } catch (ServiceEx ex) {
            //异常处理
            result.setSuccess(false);
            result.setCode(ResultCode.SYSTEM_ERROR.getCode());
            result.setMessage(ex.getMessage());
        }

    }
    return result;
}
}

是不是觉得很繁琐？
没错，这里有许多值得优化的地方，接下来我会带大家一步一步优化controller层的代码，最终实现只需要写一行就能完成所有的工作。

1.统一封装返回对象

首先，我们看到这里无论是业务成功或者失败，都需要封装返回对象，非常麻烦，我们应该就能想到把封装返回对象的逻辑抽象出来，写到一个BaseController类中，供所有的controller继承：

/**
 * @Author: Sawyer
 * @Description: 基础controller，用来包装http返回对象
 * @Date: Created in 上午10:43 17/8/11
 */
public abstract class BaseController {

/**
 * 默认成功返回
 *
 * @param data
 * @return
 */
protected <T> HttpResult<T> responseOK(T data) {
    HttpResult<T> restResult = new HttpResult<>();
    restResult.setSuccess(true);
    restResult.setData(data);
    restResult.setCode(ResultCode.SUCCESS.getCode());
    restResult.setMessage(ResultCode.SUCCESS.getMessage());
    return restResult;
}

/**
 * 默认成功返回带消息
 *
 * @param data
 * @param msg
 * @return
 */
protected <T> HttpResult<T> responseOK(T data, String msg) {
    HttpResult<T> restResult = new HttpResult<>();
    restResult.setSuccess(true);
    restResult.setData(data);
    restResult.setCode(ResultCode.SUCCESS.getCode());
    restResult.setMessage(msg);
    return restResult;
}

/**
 * 默认失败返回, 不带参数
 *
 * @return
 */
protected <T> HttpResult<T> responseFail() {
    return responseFail(ResultCode.SYSTEM_ERROR);
}

/**
 * 默认失败返回, 带信息
 *
 * @param message 
 * @return
 */
protected <T> HttpResult<T> responseFail(String message) {
    return responseFail(ResultCode.SYSTEM_ERROR, message);
}

/**
 * 默认失败返回，带code
 *
 * @param code
 * @return
 */
protected <T> HttpResult<T> responseFail(ResultCode code) {
    return responseFail(code, code.getMessage());
}

/**
 * 失败返回 
 *
 * @param code    错误Code
 * @param message 若为null，则使用Code对应的默认信息
 * @return
 */
protected <T> HttpResult<T> responseFail(ResultCode code, String message) {
    HttpResult<T> restResult = new HttpResult<>();
    restResult.setSuccess(false);
    restResult.setCode(code.getCode());
    message = message == null ? code.getMessage() : message;
    restResult.setMessage(message);
    return restResult;
}
}

这个BaseController主要提供了封装返回对象的几种方法，可以满足成功或者失败的返回情况。将我们的UserController继承该类，使用这里的方法后代码变为：

@RestController
@RequestMapping("/v1/user")
public class UserController extends BaseController {

@Autowired
UserService userService;

@PutMapping("/{id}")
public HttpResult<UserDTO> updateUser(@PathVariable("id") Integer id, @RequestBody UserDTO userDTO) {
    //参数校验，UserDTO.name不能为空
    if (userDTO.getName() == null) {
        return responseFail("name不能为空");
    } else {
        //调用service更新user，更新可能抛出异常，要捕获
        try {
            User updatedUser = userService.updateUser(id, userDTO);
            //转换对象，转化DO为DTO
            UserDTO updatedDto = new UserDTO();
            BeanUtils.copyProperties(updatedUser, updatedDto);
            if (GenderEnum.MALE.getCode() == updatedUser.getGender()) {
                updatedDto.setGenderDesc(GenderEnum.MALE.name());
            } else {
                updatedDto.setGenderDesc(GenderEnum.FEMALE.name());
            }
            return responseOK(updatedDto);
        } catch (ServiceEx ex) {
            //异常处理
            return responseFail();
        }
    }
}
}

2.对象转化方法抽象

这里我们将User转化为了UserDTO对象，并且根据User中的gender属性设置了dto中相应genderDesc的值，我们也很容易想到这个转化方法应该具有通用性，所以可以直接放到UserDTO中：

public class UserDTO {

private Integer id;

private String name;

private String gender;

private String genderDesc;

private Date createdTime;

public static UserDTO convert(User user) {
    Assert.notNull(user, "user不能为空");
    UserDTO dto = new UserDTO();
    BeanUtils.copyProperties(user, dto);
    if (GenderEnum.MALE.getCode() == user.getGender()) {
        dto.setGenderDesc(GenderEnum.MALE.name());
    } else {
        dto.setGenderDesc(GenderEnum.FEMALE.name());
    }
    return dto;
}
//getter and setter
}

那么我们的UserController的代码可改写为：

@RestController
@RequestMapping("/v1/user")
public class UserController extends BaseController {

@Autowired
UserService userService;

@PutMapping("/{id}")
public HttpResult<UserDTO> updateUser(@PathVariable("id") Integer id, @RequestBody UserDTO userDTO) {
    //参数校验，UserDTO.name不能为空
    if (userDTO.getName() == null) {
        return responseFail("name不能为空");
    } else {
        //调用service更新user，更新可能抛出异常，要捕获
        try {
            return responseOK(UserDTO.convert(userService.updateUser(id, userDTO)));
        } catch (ServiceEx ex) {
            //异常处理
            return responseFail();
        }
    }
}
}

3.参数校验在对象中做

其实大多数的参数校验无非就是判空或者空字符串，那么我们可以好好利用javax.validation为我们提供的@NotNull等注解。在UserDTO类中name属性上加上@NotNull字段：

@NotNull(message = "name不能为空")
private String name;

并且在形参上加上@Valid注解，这样javax.validation将会帮我们校验参数：

@RestController
@RequestMapping("/v1/user")
public class UserController extends BaseController {

@Autowired
UserService userService;

@PutMapping("/{id}")
public HttpResult<UserDTO> updateUser(@PathVariable("id") Integer id, @Valid @RequestBody UserDTO userDTO) {
    //调用service更新user，更新可能抛出异常，要捕获
    try {
        return responseOK(UserDTO.convert(userService.updateUser(id, userDTO)));
    } catch (ServiceEx ex) {
        //异常处理
        return responseFail();
    }
}
}

除了简单的非空判断以外，我们也可以通过自定义注解来实现更复杂的逻辑判断，这里就不展开了，感兴趣的同学可以自行百度。
有的朋友要问了，不对啊，你这要是没通过验证会返回500服务器错误的啊，别急，我们来看最后一步。

4.统一的异常捕获

如果sevice层的代码都会抛出异常，难道我们需要在每个controller层的方法中都做try-catch吗？显然不是，我们可以给controller层的方法加上切面来统一处理异常。spring给我们提供了@ControllerAdvice注解，用来定义controller层的切面，所有@Controller注解的类中的方法执行都会进入该切面，同时我们可以使用@ExceptionHandler来对不同的异常进行捕获和处理，对于捕获的异常，我们应该进行日志记录，并且封装返回对象：

/**
 * @Author: Sawyer
 * @Description: 统一异常处理
 * @Date: Created in 上午11:17 17/8/11
 */
@ControllerAdvice
@RestController
public class ExceptionAdvice extends BaseController {

@Autowired
HttpServletRequest httpServletRequest;

/**
 * 
 * 异常日志记录
 *
 * @param e
 */
private void logErrorRequest(Exception e) {
    String info = String.format("报错API URL: %s%nQuery String: %s",
            httpServletRequest.getRequestURI(),
            httpServletRequest.getQueryString());
    ApiLogger.runLogger.error(info);
    ApiLogger.exceptionLogger.error(e.getMessage(), e);
    String ipInfo = "报错访问者IP信息：" + httpServletRequest.getRemoteAddr() + "," + httpServletRequest.getRemoteHost();
    ApiLogger.runLogger.error(ipInfo);
}

/**
 * 参数校验异常
 *
 * @param exception
 * @return
 */
@ExceptionHandler(MethodArgumentNotValidException.class)
protected HttpResult methodArgumentNotValid(MethodArgumentNotValidException exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.INVALID_PARAM);
}

/**
 * 参数格式有误
 *
 * @param exception
 * @return
 */
@ExceptionHandler({MethodArgumentTypeMismatchException.class, HttpMessageNotReadableException.class})
protected HttpResult typeMismatch(Exception exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.MISTYPE_PARAM);
}

/**
 * 缺少参数
 *
 * @param exception
 * @return
 */
@ExceptionHandler(MissingServletRequestParameterException.class)
protected HttpResult missingServletRequestParameter(MissingServletRequestParameterException exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.MISSING_PARAM);
}

/**
 * 不支持的请求类型
 *
 * @param exception
 * @return
 */
@ExceptionHandler(HttpRequestMethodNotSupportedException.class)
protected HttpResult httpRequestMethodNotSupported(HttpRequestMethodNotSupportedException exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.UNSUPPORTED_METHOD);
}

/**
 * 业务层异常
 *
 * @param exception
 * @return
 */
@ExceptionHandler(ServiceEx.class)
protected HttpResult serviceException(ServiceEx exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.SYSTEM_ERROR, exception.getMessage());
}

/**
 * 其他异常
 *
 * @param exception
 * @return
 */
@ExceptionHandler({HttpClientErrorException.class, IOException.class, Exception.class})
protected HttpResult commonException(Exception exception) {
    logErrorRequest(exception);
    return responseFail(ResultCode.SYSTEM_ERROR);
}
}

上面这个切面是我日常工作在用的切面，基本涵盖了常见的web异常，在这里也可以通过@ExceptionHandler处理自定义的异常，比如这里的serviceException。回答上面遗留下来的问题，如果没有通过参数校验，那么就会被methodArgumentNotValid方法处理，并且妥善地使用baseController中的方法封装好返回对象。加上切面后，我们的UserController代码最终改写为：

@RestController
@RequestMapping("/v1/user")
public class UserController extends BaseController {

@Autowired
UserService userService;

@PutMapping("/{id}")
public HttpResult<UserDTO> updateUser(@PathVariable("id") Integer id, @Valid @RequestBody UserDTO userDTO) throws Exception { 
    return responseOK(UserDTO.convert(userService.updateUser(id, userDTO)));
}
}

怎么样？是不是变得特别简洁。通过统一的返回对象封装，统一的异常处理等，我们的controller层代码变得非常简介，这也是我个人比较推崇的代码简约之道。学会的老铁扣波666。

最后我想提的一点是，有些同学习惯在service层直接将HTTP/RPC返回对象封装好返回，我个人认为是不妥的。主要原因是如果在service就返回HTTP reponse，那么service层的互相调用都会面临先判断response的成功与否，再将reponse的data取出进行逻辑操作，十分不便。毕竟现在没有别的sevice调用，并不代表将来不会。

设计之道－controller层的设计

1.统一封装返回对象

2.对象转化方法抽象

3.参数校验在对象中做

4.统一的异常捕获

猜你喜欢

热点阅读