SpringBoot基础教程2-1-2 Controller规范及响应规范

1. 概述

基于接口编程是解耦的基本原则，工作中经常需要定义接口，看似没有什么技术难题，但需要良好的编程习惯来约束。

2. 常见“坏”接口

返回Map，可读性差

@GetMapping("/{id}")
public Map<String,String> get(@PathVariable Integer id){

}

返回Object，大忌！使用者或者维护者不知道具体返回格式，接口可以随意改动

@GetMapping("/{id}")
public Object get(@PathVariable Integer id){
    if(user =! null){
        return user;
    } else {
        return false;
    }
}

返回void，无用接口

@DeleteMapping("/{id}")
public void delete(@PathVariable Integer id){

}

参数过于复杂，如：参数出现json格式，可读性不好，代码也难看

@PostMapping("/update")
public Map<String, Object> update(long id, String jsonStr) {

}

参数为HttpServletRequest，可读性查，不利于维护

@PostMapping("/update")
public Object update(HttpServletRequest request) {

}

3. Controller规范

RESTful风格，推荐阅读上一篇SpringBoot基础教程，搭建RESTful风格Web服务

4. 统一响应规范

建议所有接口返回统一的格式R，方便调用者封装

public class R<T> implements Serializable {

    private T data; //服务端数据
    private int status = 0; //状态码，0：成功，1：失败
    private String msg = ""; //描述信息

    // 省略 set get

    public static R isOk() {
        return new R().msg("成功");
    }

    public static R isFail() {
        return new R().status(1).msg("失败");
    }

    public static R isFail(Throwable e) {
        return isFail().msg(e);
    }

    public R msg(Throwable e) {
        this.setMsg(e.toString());
        return this;
    }

    public R data(T data) {
        this.setData(data);
        return this;
    }

    public R msg(String msg){
        this.setMsg(msg);
        return this;
    }

    public R status(int status) {
        this.setStatus(status);
        return this;
    }
}

Controller中如何使用

@RequestMapping("/users")
@RestController
public class UserController {
    @GetMapping("/ok")
    public R<User> ok(){
        User user  = new User();
        user.setUserId(1);
        user.setName("Mkeeper");
        user.setAge(28);

        return R.isOk().data(user);
    }

    @GetMapping("/fail")
    public R<Object> fail(){
        return R.isFail();
    }

    @GetMapping("/exception")
    public R<Object> exception(){

        return R.isFail(new Exception("失败"));
    }
}

测试结果

注意

• R只允许再Controller层使用，不允许往后传，类似传Map，json；可读性大大降低
• Contorller只做参数格式转换，如果没有参数需要转换的，那么就一行代码。日志/参数校验/权限判断建议放到service里面，毕竟controller基本无法重用，而service重用较多。而我们的单元测试也不需要测试controller，直接测试service即可。

5. 工程目录

6. 结束语

良好的编程风格，是高效的前提，技术固然重要，好习惯让你事半功倍。有任何建议，欢迎留言探讨，本文源码。

---

欢迎关注博主公众号：Java十分钟