易鹏扩展注解介绍

为简化开发者的使用成本与开发难度，易鹏特别扩展了一系列注解工具，便于开发者快速上手、高效使用

Swagger扩展注解

@KPApiJsonParam

作用：对入参是JSON的(@RequestBody)生成接口参数说明

用法及效果

示例一

java

@PreAuthorize("hasPermission('/auth/role/add/user','auth:role:add:user')")
@Operation(summary = "设置用户", description = "权限 auth:role:add:user")
@KPApiJsonParam({
  @KPJsonField(name = "roleId", description = "角色Id", required = true),
  @KPJsonField(name = "userIds", description = "用户id集合", required = true, dataType = "array<string>")
})
@PostMapping(value = "/add/user")
public KPResult<Void> roleAddUser(@RequestBody JSONObject parameter) {
  userRoleService.userRoleService(parameter);
  return KPResult.success();
}

效果图 img10

示例二

java

@PreAuthorize("hasPermission('/auth/user/batch/cancel','auth:user:batch:cancel')")
@Operation(summary = "批量注销", description = "权限 auth:user:batch:cancel")
@PostMapping(value = "/batch/cancel")
@KPApiJsonParam({
        @KPJsonField(name = "ids", description = "用户Id", required = true, dataType = "array<string>")
})
@KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.UPDATE_BATCH, businessType = "用户信息")
public KPResult<String> doCancel(@RequestBody List<String> ids) {
    return KPResult.success(userService.doCancel(ids));
}

效果图 img10

@KPApiJsonParamMode

作用：对入参是JSON的(@RequestBody)生成接口参数说明，从现有的实体类上抽取指定的字段或屏蔽指定的字段

参数说明：

separator：分隔符，默认是英文逗号

component：目标实体类

ignores：忽略的字段

includes：包含的字段

用法及效果

示例一

java

@Operation(summary = "查询用户信息-不带分页")
@PostMapping(value = "/list")
@KPApiJsonParamMode(component = UserListParamPO.class, ignores = "pageNum,pageSize")
public KPResult<List<UserListCustomerPO>> queryList(@RequestBody UserListParamPO userListParamPO) {
    return KPResult.success(userService.queryList(userListParamPO));
}

效果图 img11

示例二

java

@Operation(summary = "查询部门下拉框")
@PostMapping("/dept/select")
@KPApiJsonParamMode(component = DeptListParamPO.class, includes = "isTree")
public KPResult<List<DictionaryChildrenBO>> queryProjectSelect(@RequestBody DeptListParamPO deptListParamPO) {
  return KPResult.success(KPServiceUtil.getBean(DeptService.class).queryDeptSelect(deptListParamPO));
}

效果图 img13

权限注解

@PreAuthorize

作用：Spring Security 权限注解，用于在接口调用之前对用户权限进行验证。易鹏框架进行二次开发，用于验证权限
参数说明：
hasPermission：设置访问权限，第一个参数表示接口全路径，第二个参数表示权限标识

补充：权限控制具体操作，请查看权限配置

用法

java

  #表示调用该接口，用户必须有auth:user:save权限，权限控制具体查看权限配置说明
  @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
  @Operation(summary = "新增用户信息", description = "权限 auth:user:save")
  @PostMapping("/save")
  @KPApiJsonParamMode(component = UserEditParamPO.class, ignores = "userId")
  @KPObjectChangeLogListNote({
          @KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.ADD, businessType = "用户信息"),
          @KPObjectChangeLogNote(parentMapper = UserDeptMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.ADD_BATCH, businessType = "用户所属部门"),
          @KPObjectChangeLogNote(parentMapper = UserRoleMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.ADD_BATCH, businessType = "用户所属角色"),
          @KPObjectChangeLogNote(parentMapper = UserPostMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.ADD_BATCH, businessType = "用户所属岗位"),
          @KPObjectChangeLogNote(parentMapper = UserProjectMapper.class, identification = "userId,user_id", operateType = ObjectChangeLogOperateType.ADD_BATCH, businessType = "用户可操作项目")
  })
  @KPVerifyNote
  public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO) {
      userService.saveUser(userEditParamPO);
      return KPResult.success();
  }

@KPDataPermissions

作用：用于验证数据权限，数据权限控制在鉴权系统进行
参数说明：
userFileName：用户ID字段，默认create_user_id
deptFileName：默认ID字段，默认dept_id
excludeTableName：要排除的表名，多个表用逗号分隔（如果我们的接口执行多个查询语句，但有的查询语句不需要在WHERE自动拼接数据权限）

补充：添加该注解后，查询的SQL语句会自动根据当前用户角色设置的数据权限进行过滤（在最终查询语句中自动拼接WHERE条件，无需程序员添加数据权限过滤条件）。如果用户有多个角色，则取最大数据权限进行查询

用法以配置方式

java

  @PreAuthorize("hasPermission('/auth/post/page/list', 'auth:post:page:list')")
  @Operation(summary = "查询岗位信息分页列表", description = "权限 auth:post:page:list")
  @PostMapping("/page/list")
  @KPDataPermissions(excludeTableName="auth_user")
  @KPVerifyNote
  public KPResult<PostPO> queryList(@RequestBody PostListParamPO postListParamPO){
      return KPResult.list(postService.queryPageList(postListParamPO));
  }

数据权限设置方式在角色列表中数据权限配置页面进行配置效果图 img14 效果图 img15 效果图 img16

校验器注解

@KPVerifyNote

作用：开启注解校验
说明：易鹏框架开发了自己的注解校验器，简化用户对应参数的校验。如果使用注解校验器，需要先在接口上使用@KPVerifyNote打开注解校验器。如果不加该注解，即使使用了注解校验也不起作用

补充：注解校验器底层实现是易鹏工具类中KPVerifyUtil校验方法，KPVerifyUtil提供全量的校验方法。单注解目前只提供以下注解，其他的会在后续新增

用法

java

  @PreAuthorize("hasPermission('/auth/post/save','auth:post:save')")
  @Operation(summary = "新增岗位信息", description = "权限 auth:post:save")
  @PostMapping("/save")
  @KPObjectChangeLogNote(parentMapper = PostMapper.class, identification = "postId,post_id", operateType = ObjectChangeLogOperateType.ADD, businessType = "岗位信息")
  @KPVerifyNote
  @KPApiJsonParamMode(component = PostEditParamPO.class, ignores = "postId")
  public KPResult<PostPO> save(@RequestBody PostEditParamPO postEditParamPO) {
      postService.savePost(postEditParamPO);
      return KPResult.success();
  }

@KPNotNull

作用：非空校验
说明：加在实体类上用于校验非空，不限数据类型，任何类型都可进行校验

参数说明：

errMeg：校验失败提示语

用法

java

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@Schema(name = "PostEditParamPO对象", description = "岗位信息编辑入参")
public class PostEditParamPO implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;

    @Schema(description = "岗位Id", example = "岗位Id", requiredMode = Schema.RequiredMode.REQUIRED)
    @TableId(value = "post_id", type = IdType.ASSIGN_UUID)
    @KPNotNull(errMeg = "请输入岗位Id")
    @KPMaxLength(max = 36, errMeg = "岗位Id不能超过36个字符")
    private String postId;
}

@KPMaxLength

作用：最大长度校验
说明：加在实体类上用于字段最大长度校验，不限数据类型，任何类型都可进行校验

参数说明：

errMeg：校验失败提示语

max：最大长度，如果是字符串表示长度，如果是数字表示最大数

用法

java

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@Schema(name = "PostEditParamPO对象", description = "岗位信息编辑入参")
public class PostEditParamPO implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;

    @Schema(description = "岗位Id", example = "岗位Id", requiredMode = Schema.RequiredMode.REQUIRED)
    @TableId(value = "post_id", type = IdType.ASSIGN_UUID)
    @KPNotNull(errMeg = "请输入岗位Id")
    @KPMaxLength(max = 36, errMeg = "岗位Id不能超过36个字符")
    private String postId;
}

@KPLength

作用：长度校验
说明：加在实体类上用于长度校验，不限数据类型，任何类型都可进行校验

参数说明：

errMeg：校验失败提示语

min：最小值，如果是字符串表示长度，如果是数字表示最小数

max：最大值，如果是字符串表示长度，如果是数字表示最大数

用法

java

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@Schema(name = "PostEditParamPO对象", description = "岗位信息编辑入参")
public class PostEditParamPO implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;

    @Schema(description = "岗位编码", example = "岗位编码", requiredMode = Schema.RequiredMode.REQUIRED)
    @TableField("post_code")
    @KPNotNull(errMeg = "请输入岗位编码")
    @KPLength(min = 2, max = 64, errMeg = "岗位编码须2~64个字符")
    private String postCode;
}

其他注解

@KPExcludeInterfaceJournal

作用：排除记录接口日志

说明：易鹏框架会记录所有接口调用日志，如果某些接口不想记录，可以加入该接口进行屏蔽记录

用法

java

  @Operation(summary = "查询首页用户登录数")
  @KPExcludeInterfaceJournal
  @PostMapping("/login/number")
  public KPResult<List<LoginNumberCustomerPO>> queryLoginNumber(@RequestBody List<String> projectCodes) {
      return KPResult.success(welcomeService.queryLoginNumber(projectCodes));
  }

如果不加入@KPExcludeInterfaceJournal注解，就会记录调用日志，可以在以下页面进行查询调用记录效果图 img17

@KPRepeatSubmitNote

作用：防抖注解，用于防止重复提交
说明：添加该注解后可以防止用户（同一个用户）重复提交

参数说明：

value：间隔时间，单位毫秒，默认是800毫秒，表示用户在800毫秒内只能点击一次

用法

java

  @PostMapping("/login")
  @Operation(summary = "普通登录")
  @KPApiJsonParam({
      @KPJsonField(name = "userName", description = "用户账号", required = true, example = "admin1"),
          @KPJsonField(name = "password", description = "密码", required = true, example = "admin1admin1"),
          @KPJsonField(name = "projectCode", description = "项目编号", required = true, example = "authentication"),
  })
  @KPRepeatSubmitNote(1000) # 表示同一用户在1秒内只能点击一次，如果不设置1000则默认是800毫秒
  public KPResult<UserLoginCustomerPO> login(@RequestBody JSONObject parameter) {
      return KPResult.success(loginService.login(parameter));
  }

效果图 img18

@KPProhibitCrawlerNote

作用：禁止爬虫，用于防止关键接口数据被爬虫抓取
说明：添加该注解后可以有效保护关键接口数据被爬虫抓取
参数说明：
minute：间隔时间，单位分，默认是5分
minuteCount：接口调用次数，默认50次
forbidHouse：禁止访问时间，单位小时，默认12小时
blacklist：禁止访问次数，默认3次

补充：如果接口添加该注解@KPProhibitCrawlerNote不设置任何参数，表示用户5分钟内最多访问该接口50次。如果5分钟超过50次，加入临时黑名单，12小时内禁止访问，同时临时黑名单次数+1。当用户临时黑名单次数超过3次，则加入永久黑名单禁止访问。加入永久黑名单后，相当于该用户永远无法再获取该接口数据

用法

java

  @PreAuthorize("hasPermission('/auth/user/page/list', 'auth:user:page:list')")
  @Operation(summary = "查询用户信息分页列表", description = "权限 auth:user:page:list")
  @PostMapping("/page/list")
  @KPVerifyNote
  @KPProhibitCrawlerNote(minute = 10, minuteCount = 70)
  public KPResult<UserListCustomerPO> queryPageList(@RequestBody UserListParamPO userListParamPO){
      return KPResult.list(userService.queryPageList(userListParamPO));
  }

@KPObjectChangeLogNote

作用：数据库表字段修改记录
说明：添加该注解后可以记录指定表里面所有字段变更记录，无需开发人员手动记录变化，例如用户记录用户名从admin变为adm，性别男变为女
参数说明：
parentMapper：查询数据库所调用的Mapper类
identification：唯一标识(数据库主键)，查询数据库的条件，如果数据库字段和实体表字段名称不一样，写字段名称|数据库字段名称，如houseId|house_id，用英文逗号分隔
operateType：操作类型，填充ObjectChangeLogOperateType，如ObjectChangeLogOperateType.ADD
businessType：业务类型，使用者自己扩展
saveDS：保存日志的数据源，默认yipeng_auth
saveTableName：保存日志的数据库表名，默认auth_object_change_log
notRecordField：不记录的改变字段，默认createDate,updateDate,deleteFlag

补充：添加注解后会自动记录指定数据表中字段改变内容，开发人员无需开发，只需要前端展示一个变化轨迹页面即可

用法

java

  @PreAuthorize("hasPermission('/auth/role/save','auth:role:save')")
  @Operation(summary = "新增角色信息", description = "权限 auth:role:save")
  @PostMapping("/save")
  @KPVerifyNote
  @KPObjectChangeLogNote(parentMapper = RoleMapper.class, identification = "roleId,role_id", operateType = ObjectChangeLogOperateType.ADD, businessType="角色")
  @KPApiJsonlParamMode(component = RoleEditParamPO.class, ignores = "roleId")
  public KPResult<RolePO> save(@RequestBody RoleEditParamPO roleEditParamPO) {
      roleService.saveRole(roleEditParamPO);
      return KPResult.success();
  }

  @PreAuthorize("hasPermission('/auth/role/update','auth:role:update')")
  @Operation(summary = "修改角色信息", description = "权限 auth:role:update")
  @PostMapping("/update")
  @KPObjectChangeLogNote(parentMapper = RoleMapper.class, identification = "roleId,role_id", operateType = ObjectChangeLogOperateType.UPDATE, businessType="角色")
  @KPVerifyNote
  public KPResult<RolePO> update(@RequestBody RoleEditParamPO roleEditParamPO) {
      roleService.updateRole(roleEditParamPO);
      return KPResult.success();
  }

效果图 img19 效果图 img20

@KPObjectChangeLogListNote

作用：多张数据库表修改记录，@KPObjectChangeLogNote注解的集合

说明：如果一个接口里面要记录多张表的修改记录，可以使用该注解

用法

示例一

java

  @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
  @Operation(summary = "新增用户信息", description="权限 auth:user:save")
  @PostMapping("/save")
  @KPVerifyNote
  @KPObjectChangeLogListNote({
      @KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,userId", operateType = ObjectChangeLogOperateType.ADD, businessType="用户"),
      @KPObjectChangeLogNote(parentMapper = UserRoleMapper.class, identification = "aurId,aur_id", operateType = ObjectChangeLogOperateType.ADD, businessType="用户角色")
  })
  @KPApiJsonParamMode(component = UserEditParamPO.class, ignores = "userId")
  public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO){
      userService.saveUser(userEditParamPO);
      return KPResult.success();
  }

示例二

java

  @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
  @Operation(summary = "新增用户信息", description="权限 auth:user:save")
  @PostMapping("/save")
  @KPVerifyNote
  @KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,userId", operateType = ObjectChangeLogOperateType.ADD, businessType="用户")
  @KPObjectChangeLogNote(parentMapper = UserRoleMapper.class, identification = "aurId,aur_id", operateType = ObjectChangeLogOperateType.ADD, businessType="用户角色")
  @KPApiJsonParamMode(component = UserEditParamPO.class, ignores = "userId")
  public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO){
      userService.saveUser(userEditParamPO);
      return KPResult.success();
  }

易鹏扩展注解介绍 ​

Swagger扩展注解 ​

@KPApiJsonParam ​

示例一

示例二

@KPApiJsonParamMode ​

示例一

示例二

权限注解 ​

@PreAuthorize ​

@KPDataPermissions ​

校验器注解 ​

@KPVerifyNote ​

@KPNotNull ​

@KPMaxLength ​

@KPLength ​

其他注解 ​

@KPExcludeInterfaceJournal ​

@KPRepeatSubmitNote ​

@KPProhibitCrawlerNote ​

@KPObjectChangeLogNote ​

@KPObjectChangeLogListNote ​

示例一

示例二

易鹏扩展注解介绍

Swagger扩展注解

@KPApiJsonParam

@KPApiJsonParamMode

权限注解

@PreAuthorize

@KPDataPermissions

校验器注解

@KPVerifyNote

@KPNotNull

@KPMaxLength

@KPLength

其他注解

@KPExcludeInterfaceJournal

@KPRepeatSubmitNote

@KPProhibitCrawlerNote

@KPObjectChangeLogNote

@KPObjectChangeLogListNote