RuoYi-Vue-Plus 后端 CRUD 开发规范基于分层架构的单表增删改查实战指南【免费下载链接】RuoYi-Vue-Plus多租户后台管理系统 重写RuoYi-Vue所有功能 集成 Sa-Token、Mybatis-Plus、WarmFlow、SpringDoc、Hutool、OSS 定期同步项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-PlusRuoYi-Vue-Plus 为开发者沉淀了一套标准后端 CRUD的工程规范覆盖新增单表业务时从 entity/bo/vo/mapper/service/controller 的完整搭建链路并统一了分页查询、导出、删除前校验等约定。本文以仓库中backend-crud规范文档为主体结合ruoyi-system模块中角色管理等标准实现与ruoyi-common-mybatis的底层封装源码逐层讲解这套 CRUD 开发模式的落地方式。读完本文你将掌握在 RuoYi-Vue-Plus 中新增一个标准管理模块的全部约定、关键注解用法与可复制的代码骨架。一、总览一套稳定的 CRUD 分层结构规范的首要原则是先参考、再动手先参考ruoyi-modules/ruoyi-gen模块下的代码生成器模板再参考当前模块内最近似的标准管理模块例如ruoyi-system中的角色/用户/部门等模块分层保持稳定包结构固定为domain -- 实体类Entity domain.bo -- 业务对象接收请求参数 domain.vo -- 视图对象返回前端数据 mapper -- 数据访问层 service -- 业务接口 service.impl -- 业务实现 controller -- 控制器这一约定在仓库中得到了完整印证以角色管理为例其分层文件依次位于 SysRole.java、SysRoleBo.java、SysRoleVo.java、SysRoleMapper.java、ISysRoleService.java、SysRoleServiceImpl.java、SysRoleController.java。新增业务时照此包结构对号入座即可。二、Entity 层约定基类继承与 MyBatis-Plus 注解实体Entity是数据库表的映射规范要求默认继承BaseEntityBaseEntity 位于 BaseEntity.java内置了createDept创建部门、createBy创建者、createTime创建时间、updateBy更新者、updateTime更新时间五个审计字段并全部通过TableField(fill FieldFill.INSERT / FieldFill.INSERT_UPDATE)声明了自动填充策略写入数据时无需手动赋值。表名与主键注解实体使用TableName标注表名主键字段使用TableId。逻辑删除与乐观锁若表存在delFlag逻辑删除字段、乐观锁版本字段必须保留TableLogic、Version注解由 MyBatis-Plus 自动完成逻辑删除过滤与乐观锁校验。这套约定保证了所有实体具备统一的审计字段与通用 CRUD 能力也是后续BaseMapperPlus泛型方法能够直接生效的前提。三、Mapper 层继承 BaseMapperPlusT, V规范要求 mapper 默认继承BaseMapperPlusEntity, Vo。该接口位于 BaseMapperPlus.java是对 MyBatis-PlusBaseMapper的二次封装核心能力包括泛型双绑定BaseMapperPlusT, V同时持有实体类型 T 与 VO 类型 V并通过ClassValue缓存解析结果见TYPE_ARGUMENT_CACHE避免重复反射解析。VO 直查方法族selectVoById、selectVoByIds、selectVoByMap、selectVoOne、selectVoList、selectVoPage等底层流程均为按条件查出实体列表 → 通过MapstructUtils.convert转换为 VO例如selectVoList的实现是this.selectList(wrapper)后调用MapstructUtils.convert(list, voClass)。批量操作insertBatch、updateBatchById、insertOrUpdateBatch三个批量方法底层委托 MyBatis-Plus 的Db.saveBatch/Db.updateBatchById/Db.saveOrUpdateBatch并支持自定义batchSize。链式查询入口lambda()返回LambdaCrudChainWrapperT, VlambdaUpdate()返回LambdaUpdateChainWrapperT。其中lambda()内部通过 Spring 容器获取 Mapper 代理对象mapperProxy()确保 Mapper 上的切面注解继续生效。实际使用示例来自角色模块的分页查询PageSysRoleVo page roleMapper.selectPageRoleList(pageQuery.build(), this.buildQueryWrapper(role)); return PageResult.build(page.getRecords(), page.getTotal());四、BO / VO / Entity 职责分离规范强调三层职责严格分离BO业务对象接收请求与查询扩展字段使用AutoMapper(target Entity.class, reverseConvertGenerate false)声明到实体的映射关系。reverseConvertGenerate false表示只生成BO → Entity方向的映射不反向生成。BO 上同时承载参数校验注解NotBlank、Size、NotNull等例如 SysRoleBo.java 中的角色名称校验NotBlank(message 角色名称不能为空) Size(min 0, max 30, message 角色名称长度不能超过{max}个字符) private String roleName;VO视图对象返回给前端的展示对象使用AutoMapper(target Entity.class)声明与实体的映射。展示派生字段、Translation翻译注解、导出注解ExcelProperty都放在 VO 上。例如 SysRoleVo.java 中大量使用ExcelProperty(value 角色序号)定义导出列并用ExcelProperty(value 数据范围, converter ExcelDictConvert.class)挂接字典转换器。BO/VO 转换BO 转实体统一使用MapstructUtils.convert(bo, Entity.class)MapstructUtils 位于 ruoyi-common-core由AutoMapper注解在编译期生成映射代码。五、Service 层默认方法集合标准业务 Service 接口默认包含六个方法构成了 CRUD 的完整闭环方法职责queryById按主键查询详情queryPageList分页查询列表queryList无条件/条件查询全部列表insertByBo新增接收 BOupdateByBo修改接收 BOdeleteWithValidByIds批量删除删除前进行业务校验实现要点写入前校验优先放在validEntityBeforeSave(...)方法中统一完成保证新增与修改走同一校验逻辑。业务级校验如唯一性校验、数据权限校验可在insertByBo/updateByBo内显式调用。角色模块即为典型参考新增前调用checkRoleNameUnique、checkRoleKeyUnique见 SysRoleServiceImpl.java。修改/删除后联动数据变更后可发布 Spring 事件做联动清理例如角色信息变更后发布OnlineUserCleanEvent.byRole(role.getRoleId())清理在线用户缓存。六、Controller 层接口规则与标准路由Controller 规范要点继承BaseControllerBaseController 位于 ruoyi-common-web提供toAjax(...)等通用返回转换方法。返回值统一RT或RVoid成功用R.ok(...)失败用R.fail(...)。标准 CRUD 路由以 SysRoleController.java 为模板方法路由说明GET/list分页列表返回RPageResultVoPOST/export导出 ExcelGET/{id}查询详情POST空新增PUT空修改DELETE/{ids}批量删除ids逗号分隔注解使用约定每个接口按需添加SaCheckPermission权限校验权限标识遵循${module}:${business}:${action}三段式例如system:role:list、system:role:add、system:role:edit、system:role:export写操作增删改添加Log(title ..., businessType BusinessType.INSERT / UPDATE / DELETE / EXPORT)记录操作日志新增与修改添加RepeatSubmit()防重复提交注解位于 ruoyi-common-redis请求参数 BO 使用Validated RequestBody触发校验。导出接口固定为POST /export实现方式参考角色模块Log(title 角色管理, businessType BusinessType.EXPORT) SaCheckPermission(system:role:export) PostMapping(/export) public void export(SysRoleBo role, HttpServletResponse response) { ListSysRoleVo list roleService.selectRoleList(role); ExcelBuilder.of(list, SysRoleVo.class).sheetName(角色数据).toResponse(response); }ExcelBuilder位于 ruoyi-common-excel基于 VO 上的ExcelProperty注解自动生成 Excel 响应流。七、查询规则QueryBuilder、LambdaQueryCondition 与分页规范对查询层有明确的统一约定1. 查询构造入口单表查询优先返回LambdaQueryWrapper新增 generator 风格代码优先使用QueryBuilder.lambda(Entity.class).build()。QueryBuilder位于 QueryBuilder.java提供三个静态入口lambda(ClassT entityClass)单表 Lambda 查询内部构造AggregateLambdaQueryWrapperlambdaJoin(ClassT entityClass)基于 MPJMyBatis-Plus Join的联表查询lambdaJoin(String alias, ClassT entityClass)带主表别名的联表查询。2. 链式条件风格项目的公共链式查询支持QueryBuilder.lambda(...)、BaseMapperPlus#lambda()、LambdaCrudChainWrapper、LambdaQueryCondition四种风格。其中LambdaQueryCondition位于 LambdaQueryCondition.java扩展了eq/ne/gt/ge/lt/le等条件方法统一支持布尔condition参数控制条件是否生效并在此基础上封装了IfPresent/IfText/IfNotEmpty风格方法——当入参为空时自动跳过该条件避免手写大量if (x ! null)判断。3. 日期范围约定日期范围查询默认从bo.getParams()中读取begin/end键值。BO 通常内置MapString, Object params字段存放这类非结构化查询扩展参数Service 层构建 Wrapper 时从中提取beginTime/endTime拼接到查询条件。4. 分页返回约定分页优先返回PageResultVo。PageQuery位于 PageQuery.java封装了pageNum默认 1、pageSize默认Integer.MAX_VALUE、orderByColumn、isAsc四个分页参数提供build()方法将其转换为 MyBatis-Plus 的Page对象PageResult.build(records, total)位于 PageResult.java统一组装分页响应结构。5. 实体转换BO 转实体统一使用MapstructUtils.convert(bo, Entity.class)与AutoMapper注解配合实现编译期类型安全映射。八、代码生成器与模板约定规范的起点是代码生成器。文档约定生成器模板位于ruoyi-modules/ruoyi-gen/src/main/resources/vm/下注当前仓库快照中该资源目录未随代码一并提交若需查看模板需在本地生成环境执行代码生成命令后产出生成器模块的核心逻辑位于 GenController.java、GenTableServiceImpl.java 与 GenUtils.java。使用生成器时需注意一个命名约定代码生成器模板按类名首字母小写命名 Mapper 字段例如SysRoleMapper→sysRoleMapper手写业务代码时则可以使用具体业务短名。即由生成器产出的 Service 实现中Mapper 注入字段名一律取类名首字母小写而手写业务时可以用更贴合业务语义的短名。这一约定保证了生成代码与手写代码在团队内保持一致的辨识度。此外规范明确不能只满足于 generator 裸产物生成后需要继续补齐项目约定——包括 BO/VO 职责分离是否到位、导出与分页与删除前校验是否齐全、权限标识是否按三段式规范命名等最终交付的是符合工程规范的代码而非能跑就行的生成物。九、前端同步约定CRUD 改动往往伴随前端联调规范要求前端api/types与 Vue 的index.vue或 React 的index.tsx同步更新且必须与后端保持一致接口路径与后端 Controller 路由一一对应/list、/export、/{id}、POST、PUT、DELETE /{ids}返回结构列表接口对应PageResultVo结构其余接口对应RT/RVoid结构日期范围参数查询表单提交的日期区间字段名begin/end或自定义别名需与后端bo.getParams()中读取的键一致否则会导致查询条件丢失。十、交付前自检清单规范在最后给出了 CRUD 交付前的自检项这也是每次新增模块的验收标准CRUD 链路是否完整queryById、queryPageList、queryList、insertByBo、updateByBo、deleteWithValidByIds六个默认方法是否齐全BO / VO / Entity 职责是否分离请求与查询扩展字段是否放在 BO展示派生字段与翻译/导出注解是否放在 VO导出、分页、删除前校验是否齐全POST /export导出、PageResultVo分页、validEntityBeforeSave/ 删除前业务校验是否都已实现是否只是 generator 裸产物如果是需要继续补齐项目约定权限标识、日志注解、防重复提交、命名规范等前端是否同步api/types与页面组件的接口路径、返回结构、日期范围参数是否与后端一致。以 SysRoleController.java 为代表的角色管理模块就是上述全部约定的完整落地样例——从SaCheckPermission权限、Log日志、RepeatSubmit防重、PageResult分页到ExcelBuilder导出一应俱全可作为新增单表 CRUD 模块时的最近似标准管理模块参照物直接对照开发。【免费下载链接】RuoYi-Vue-Plus多租户后台管理系统 重写RuoYi-Vue所有功能 集成 Sa-Token、Mybatis-Plus、WarmFlow、SpringDoc、Hutool、OSS 定期同步项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-Plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考