一、Controller层的职责

controller层的职责：是对用户的数据进行校验、组织、重组、转换等，之后调用service层或者repository层对业务数据进行处理，同时对service/repository层进行包装，不应该预约其职责进行业务的处理和数据层的读写
经典的controller代码结构如下：

@ApiOperation(value = "获取首页数据", notes = "获取首页数据")
@ResponseStatus(HttpStatus.OK)
@GetMapping
public ResponseData index(HttpServletRequest request) {    
    // 校验参数
    validParams(request);
   
    // 包装并转换参数
    BizData data = extractParam(request);
    
    // 调用服务 A
    Data data1 = serviceA.call(data);
    
    // 调用服务 B
    Data data2 = serviceB.call(data);
    
    // 包装返回结果
    Data result = wrap(data1, data2);
    
    return result;
}

@ApiOperation(value = "创建Banner数据", notes = "创建Banner数据")
@ResponseStatus(HttpStatus.CREATED)
@PostMapping
public Banner create(@ApiParam(value = "Banner信息") @RequestBody Banner banner) {
    
    // 校验参数
    validBanner(banner);
    
    // 调用服务，并（包装）返回结果
    return bannerRepository.save(banner);
}

二、返回值规范

对外提供接口的返回值规范，建议采用如下返回值结构规范

public class ApiResult<T> implements Serializable {

    private static final long serialVersionUID = -7723411693664353214L;

    private T data;
    private Integer code;
    private String message;
}

数据结构主要分为三部分：
1、返回码（code）：该部分标识本次调用的结果码
2、提示信息（message）:如果有的话（通常错误的时候应该要提供）
3、数据对象（T）：支持泛型（通常错误的时候可能没有）

重要：服务提供者有义务将调用是否成功的逻辑封装到内部（如自定义isSuccess()方法返回true/false）,而不是仅仅返回code消费者去判定

完成的ApiResult代码

/**
 * 统一接口返回结果
 *
 * Time: 2018/12/29 : 15:57
 */
@Data
public class ApiResult<T> {

    protected int code;

    protected String message;

    protected T data;
    /**
     * 结果是否成功的标记
     *
     * @return 是否成功的标记
     */
    public boolean isSuccess() {
        return code == ResultEnum.SUCCESS.getCode();
    }

    public ApiResult() {
    }

    public ApiResult(int code) {
        this.code = code;
    }

    public ApiResult(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }
 /**
     * 返回成功
     *
     * @return 成功结果
     */
    public static ApiResult success() {
        return success(null);
    }

    /**
     * 返回成功
     *
     * @return 成功结果
     */
    public static ApiResult success(String message) {
        return success(message, null);
    }

    /**
     * 返回带数据结果
     *
     * @param data 数据
     * @return 携带数据结果
     */
    public static <T> ApiResult<T> success(T data) {
        return success(null, data);
    }

    /**
     * 返回带数据结果
     *
     * @param data 数据
     * @return 携带数据结果
     */
    public static <T> ApiResult<T> success(String message, T data) {
        ApiResult<T> result = new ApiResult<>(ResultEnum.SUCCESS.getCode());
        result.setMessage(message);
        result.setData(data);
        return result;
    }

    /**
     * 返回失败
     *
     * @param result 返回结果
     * @return 失败结果
     */
    public static <T> ApiResult<T> failure(ResultEnum result) {
        return failure(result.getCode(), result.getMessage());
    }

    /**
     * 返回失败
     *
     * @param code    返回码
     * @param message 返回信息
     * @return 失败结果
     */
    public static <T> ApiResult<T> failure(int code, String message) {
        return failure(code, message, null);
    }

    /**
     * 返回失败
     *
     * @param code    返回码
     * @param message 返回信息
     * @param data    数据
     * @return 失败结果
     */
    public static <T> ApiResult<T> failure(int code, String message, T data) {
        if (code == ResultEnum.SUCCESS.getCode()) {
            throw new IllegalArgumentException("错误码[" + code + "]不能和成功的编码一样");
        }
        return new ApiResult<>(code, message, data);
    }
}

Controller注解规范

注解规范1

注解规范2