设计之道－controller层的设计

最近想把平时工作中总结出来的一些技巧和最佳实践分享给大家，主要包含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转化为“女”等。

代码结构.png

了解了工程结构后，我们可以来讲讲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调用，并不代表将来不会。

最后编辑于：2018.11.19 10:44:39

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 158,736评论 4赞 362
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 67,167评论 1赞 291
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 108,442评论 0赞 243
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 43,902评论 0赞 204
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 52,302评论 3赞 287
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 40,573评论 1赞 216
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 31,847评论 2赞 312
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 30,562评论 0赞 197
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 34,260评论 1赞 241
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 30,531评论 2赞 245
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 32,021评论 1赞 258
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 28,367评论 2赞 253
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 33,016评论 3赞 235
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 26,068评论 0赞 8
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 26,827评论 0赞 194
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 35,610评论 2赞 274
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 35,514评论 2赞 269

设计之道－controller层的设计

1.统一封装返回对象

2.对象转化方法抽象

3.参数校验在对象中做

4.统一的异常捕获

推荐阅读更多精彩内容