# Controller接口

# BaseController

BaseController是BaseCrudRestController的父类,提供请求参数处理等方法的封装。

# BaseCrudRestController

增删改查通用controller, Entity对应的controller都可以继承该类,减少代码量。通用方法:

  • protected BaseService getService() 方法 该方法是用来获取当前Entity中相关的Service实例。

# 查询

  • getViewObject 获取详情页VO
JsonResult getViewObject(Serializable id, Class<VO> voClass) {...}
//子类调用示例
JsonResult jsonResult = super.getViewObject(id, UserDetailVO.class);
1
2
3

该方法用于获取单个对象的详情VO视图对象。

  • getVOListWithPaging 获取列表页VO(带分页)
protected <T> JsonResult getVOListWithPaging(Wrapper queryWrapper, Pagination pagination, Class<T> clazz) {...}
//调用示例
JsonResult jsonResult = super.getVOListWithPaging(queryWrapper, pagination, UserListVO.class);
1
2
3

列表页查询与分页的url参数示例: /${bindURL}?pageSize=20&pageIndex=1&orderBy=itemValue&type=GENDAR orderBy排序: 格式为“”“”"字段:排序方式",如"id:DESC",多个以,分隔

  • getEntityList(queryWrapper),getEntityListWithPaging(queryWrapper, pagination) 返回entity对象的集合,供子类需要时调用

  • buildQueryWrapperBy* 自动构建QueryWrapper查询条件 (since v2.2):

    • buildQueryWrapperByDTO:根据DTO对象中的非空属性构建QueryWrapper查询对象。
    • buildQueryWrapperByParams:根据url参数中的非空参数与值构建QueryWrapper查询对象。

# 创建

  • createEntity 新建保存Entity
protected JsonResult createEntity(E entity) {...}
//方法调用示例
JsonResult jsonResult = super.createEntity(entity);
1
2
3
  • beforeCreate 创建之前
protected String beforeCreate(E entity)
1

该方法用来处理新建数据之前的检查/预处理逻辑,如数据校验等,供子类重写实现。

  • afterCreated 创建成功后
 protected void afterCreated(E entity)
1

该方法用来处理新建数据之后的逻辑,如日志记录等,供子类重写实现。
注意:该接口在create entity创建完成之后调用,请勿用于事务性处理。

# 更新

  • updateEntity 根据ID更新Entity
protected JsonResult updateEntity(Serializable id, E entity) {...}
//方法调用示例
JsonResult jsonResult = super.updateEntity(id, entity);
1
2
3
  • beforeUpdate 更新之前
protected String beforeUpdate(E entity)
1

该方法用来处理更新数据之前的逻辑,供子类重写实现。

  • afterUpdated 更新成功后
protected void afterUpdated(E entity)
1

该方法用来处理更新数据之后的逻辑,供子类重写实现。
注意:该接口在updated entity更新完成之后调用,请勿用于事务性处理。

# 删除

  • deleteEntity 根据ID删除Entity
protected JsonResult deleteEntity(Serializable id) {...}
//方法调用示例
JsonResult jsonResult = super.deleteEntity(id);
1
2
3
  • beforeDelete 删除之前
protected String beforeDelete(E entity)
1

该方法主要用来处理删除数据之前的逻辑,如检验是否具有删除权限等,供子类重写实现。

  • afterDeleted 删除成功后
protected void afterDeleted(E entity)
1

该方法用来处理删除数据之后的逻辑,供子类重写实现。
注意:该接口在deleted entity删除完成之后调用,请勿用于事务性处理。

# 撤销删除

since v2.3.0

  • cancelDeletedEntity 根据删除Entity的ID撤销删除
protected JsonResult cancelDeletedEntity(Serializable id) {...}
//方法调用示例
JsonResult jsonResult = super.cancelDeletedEntity(id);
1
2
3
  • afterDeletedCanceled 撤销删除成功后
protected void afterDeletedCanceled(E entity)
1

该方法用来处理撤销删除数据之后的逻辑,供子类重写实现。
注意:该接口在cancelDeleted entity撤销删除完成之后调用,请勿用于事务性处理。

# 批量删除

  • batchDeleteEntities 批量删除Entities
 //方法定义
protected JsonResult batchDeleteEntities(Collection<? extends Serializable> ids) {...}
//方法调用示例
JsonResult jsonResult = super.batchDeleteEntities(ids);
1
2
3
4
  • beforeBatchDelete 方法
protected String beforeBatchDelete(Collection<? extends Serializable> ids)
1

该方法主要用来处理批量删除数据之前的逻辑,如检验是否具有删除权限等,供子类重写实现

  • afterBatchDeleted 方法
protected void afterBatchDeleted(Collection<? extends Serializable> ids)
1

该方法用来处理撤销删除数据之后的逻辑,供子类重写实现。
注意:该接口在batchDeleted entity批量删除完成之后调用,请勿用于事务性处理。

# CommonController

since v2.4.0

# 获取选项

attachMore是用于为前端Select下拉框提供初始选项数据的通用接口。

  • 当前端展现形式为Select下拉等数据量不大的场景下可调用该接口进行初始化。
  • 当数据量较大,请通远程过滤过接口获取数据。
@PostMapping("/attachMore")
public JsonResult<Map<String, List<LabelValue>>> attachMore(@Valid @RequestBody ValidList<AttachMoreDTO> attachMoreDTOList) {
    return JsonResult.OK(super.attachMoreRelatedData(attachMoreDTOList));
}
1
2
3
4

# 远程过滤

注:该接口只可获取关联表数据,不可用于字典获取。

attachMoreFilter是用于为前端Select下拉框远程过滤获取选项数据的通用接口。

@PostMapping("/attachMoreFilter")
public JsonResult<List<LabelValue>> attachMoreFilter(@Valid @RequestBody AttachMoreDTO attachMoreDTO) {
    return JsonResult.OK(super.attachMoreRelatedData(attachMoreDTO, keyword));
}
1
2
3
4

# 数据校验

默认使用hibernate-validator进行后端数据校验。进行数据校验至少需要两步操作,在entity中设置每个字段的校验规则,以及在controller中对实体添加@Valid注解。

  • 在entity中对字段进行校验规则的设置
@NotNull(message = "名称不能为空")
@Length(max=100, message="名称长度应小于100")
@TableField()
private String name;
1
2
3
4
  • 在controller中添加@Valid注解
@PostMapping("/")
public JsonResult createEntity(@Valid Demo entity, BindingResult result)
        throws Exception{
    return super.createEntity(entity, result);
}
1
2
3
4
5
  • 如果您使用json格式进行数据提交,那么可以在@RequestBody注解前添加@Valid注解,如下:
public JsonResult createEntity(@Valid @RequestBody Demo entity, BindingResult result)
        throws Exception{
    return super.createEntity(entity, result);
}
1
2
3
4

# 统一异常处理

异常处理全局实现类为DefaultExceptionHandler,继承自该类并添加@ControllerAdvice注解即可自动支持:

  • 兼容JSON请求和Html页面请求的Exception异常处理

  • Entity绑定校验的统一处理(BindException.class, MethodArgumentNotValidException.class)

  • 示例代码

@ControllerAdvice
public class GeneralExceptionHandler extends DefaultExceptionHandler{
}
1
2
3

# JsonResult 的json格式

{
    code: 0,
    msg: "OK",
    data: {
    }
}
1
2
3
4
5
6
  • 调用方式
JsonResult okResult = JsonResult.OK();
JsonResult<User> okResult = JsonResult.OK(userList);
JsonResult failResult = JsonResult.FAIL_VALIDATION("xxx验证错误");
1
2
3
  • Status状态码定义:
    //请求处理成功
    OK(0, "操作成功"),

    // 部分成功(一般用于批量处理场景,只处理筛选后的合法数据)
    WARN_PARTIAL_SUCCESS(1001, "部分成功"),

    //有潜在的性能问题
    WARN_PERFORMANCE_ISSUE(1002, "潜在的性能问题"),

    // 传入参数不对
    FAIL_INVALID_PARAM(4000, "请求参数不匹配"),

    // Token无效或已过期
    FAIL_INVALID_TOKEN(4001, "Token无效或已过期"),

    // 没有权限执行该操作
    FAIL_NO_PERMISSION(4003, "无权执行该操作"),

    // 请求资源不存在
    FAIL_NOT_FOUND(4004, "请求资源不存在"),

    // 数据校验不通过
    FAIL_VALIDATION(4005, "数据校验不通过"),

    // 操作执行失败
    FAIL_OPERATION(4006, "操作执行失败"),

    // 请求连接超时
    FAIL_REQUEST_TIMEOUT(4008, "请求连接超时"),

    // 系统异常
    FAIL_EXCEPTION(5000, "系统异常"),

    // 服务不可用
    FAIL_SERVICE_UNAVAILABLE(5003, "服务不可用"),
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
  • 过滤JsonResult的返回data:

v2.2.0版本开始,JsonResult支持返回值过滤,针对不需要返回给前端的字段可以实现JsonResultFilter接口并添加Spring注解@Component,自定义filterData过滤返回数据,统一过滤处理。 示例:

@Component
public class JsonResultFilterImpl implements JsonResultFilter{
    @Override
    public <T> void filterData(T data) {
        //TODO
    }
}
1
2
3
4
5
6
7