ruoyi-vue-plus-code-patterns

name ruoyi-vue-plus-code-patterns description 基于若依-vue-plus框架的全栈代码规范指南。定义后端Java Spring Boot与前端Vue3 + TypeScript的标准化编码模式。 核心内容： - 后端分层架构规范：Controller/Service/Mapper三层设计，对象流转模式（Bo/DTO → Entity → Vo） - 前端Vue3组合式API规范：<script setup>语法糖、响应式数据管理、组件通信模式 - 数据库操作规范：MyBatis-Plus的使用规范、批量操作、事务管理 - 统一响应处理：AjaxResult封装、异常处理、日志记录 - 安全与权限：@PreAuthorize注解、数据权限、敏感字段处理 触发场景： - 编写新的业务模块（CRUD功能） - 重构旧代码或优化现有代码 - 进行代码审查（Code Review） - 解决分层架构设计问题 - 处理Vue3响应式数据丢失问题 触发关键词：代码规范、若依框架、分层架构、DTO/VO转换、对象映射、Vue3 Setup、Composition API、组件封装、响应式、MyBatis-Plus 若依框架代码规范指南 核心规范 规范1：分层架构与对象映射规范 架构层次划分： Controller层（控制器层） ：负责接收HTTP请求、参数校验、权限控制、响应封装 Service层（业务逻辑层） ：负责业务逻辑处理、事务控制、数据组装 Mapper层（数据访问层） ：负责数据库CRUD操作，仅处理数据持久化 对象流转规范： Bo (Business Object) / DTO (Data Transfer Object) ：前端传入的数据传输对象 用于接收前端表单数据 包含校验注解（@NotNull、@NotBlank等） 命名规则： 实体名称Bo.java （如 SysOrderBo.java） Entity (实体对象) ：数据库表映射对象 与数据库表结构一一对应 仅在Service层和Mapper层使用 包含MyBatis-Plus注解（@TableName、@TableId等） 命名规则： 实体名称.java （如 SysOrder.java） Vo (View Object) ：返回给前端的视图对象 用于返回给前端展示的数据 可能包含关联对象、计算字段、格式化数据 严禁直接返回Entity，避免暴露敏感字段（密码、盐值等） 命名规则： 实体名称Vo.java （如 SysOrderVo.java） 对象转换工具： 优先使用： BeanUtil.copyProperties(source, targetClass) （若依封装的Hutool工具） 复杂场景使用：MapStruct（编译期生成转换代码，性能更优） 严禁手写大量setter/getter进行属性拷贝 完整数据流转示例： 前端请求 → Bo/DTO（Controller接收） → Entity（Service处理） → Vo（Controller返回） → 前端展示 Controller层完整示例： package com.ruoyi.web.controller.system; import com.ruoyi.common.annotation.Log; import com.ruoyi.common.core.controller.BaseController; import com.ruoyi.common.core.domain.AjaxResult; import com.ruoyi.common.core.page.TableDataInfo; import com.ruoyi.common.enums.BusinessType; import com.ruoyi.common.utils.bean.BeanUtil; import com.ruoyi.system.domain.SysOrder; import com.ruoyi.system.domain.bo.SysOrderBo; import com.ruoyi.system.domain.vo.SysOrderVo; import com.ruoyi.system.service.ISysOrderService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; import java.util.List; /** * 订单管理Controller * * @author ruoyi */ @RestController @RequestMapping("/system/order") public class SysOrderController extends BaseController { @Autowired private ISysOrderService orderService; /** * 查询订单列表 * 返回类型：TableDataInfo（包含分页信息） */ @PreAuthorize("@ss.hasPermi('system:order:list')") @GetMapping("/list") public TableDataInfo list (SysOrderBo bo) { // 开启分页（从BaseController继承） startPage(); // 查询数据（Service返回Vo列表） List<SysOrderVo> list = orderService.selectOrderList(bo); // 封装分页响应 return getDataTable(list); } /** * 获取订单详细信息 * 返回类型：AjaxResult（包含单个Vo对象） */ @PreAuthorize("@ss.hasPermi('system:order:query')") @GetMapping(value = "/{orderId}") public AjaxResult getInfo ( @PathVariable Long orderId) { return success(orderService.selectOrderById(orderId)); } /** * 新增订单 * 接收流程：Bo (DTO) → 转换 Entity → Service处理 → 返回操作结果 */ @PreAuthorize("@ss.hasPermi('system:order:add')") @Log(title = "订单管理", businessType = BusinessType.INSERT) @PostMapping public AjaxResult add ( @Validated @RequestBody SysOrderBo bo) { // 1. Bo (DTO) 转 Entity SysOrder order = BeanUtil.copyProperties(bo, SysOrder.class); // 2. 调用Service（Service负责业务逻辑处理） boolean result = orderService.insertOrder(order); // 3. 返回统一响应（toAjax方法会根据boolean返回成功/失败信息） return toAjax(result); } /** * 修改订单 * 必须先校验数据权限（是否有权限修改该订单） */ @PreAuthorize("@ss.hasPermi('system:order:edit')") @Log(title = "订单管理", businessType = BusinessType.UPDATE) @PutMapping public AjaxResult edit ( @Validated @RequestBody SysOrderBo bo) { SysOrder order = BeanUtil.copyProperties(bo, SysOrder.class); return toAjax(orderService.updateOrder(order)); } /** * 删除订单（支持批量删除） * 参数：订单ID数组 */ @PreAuthorize("@ss.hasPermi('system:order:remove')") @Log(title = "订单管理", businessType = BusinessType.DELETE) @DeleteMapping("/{orderIds}") public AjaxResult remove ( @PathVariable Long[] orderIds) { return toAjax(orderService.deleteOrderByIds(orderIds)); } /** * 导出订单数据（Excel） */ @PreAuthorize("@ss.hasPermi('system:order:export')") @Log(title = "订单管理", businessType = BusinessType.EXPORT) @PostMapping("/export") public void export (HttpServletResponse response, SysOrderBo bo) { List<SysOrderVo> list = orderService.selectOrderList(bo); ExcelUtil<SysOrderVo> util = new ExcelUtil <>(SysOrderVo.class); util.exportExcel(response, list, "订单数据" ); } } Service层实现示例： package com.ruoyi.system.service.impl; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.ruoyi.common.utils.StringUtils; import com.ruoyi.common.utils.bean.BeanUtil; import com.ruoyi.system.domain.SysOrder; import com.ruoyi.system.domain.bo.SysOrderBo; import com.ruoyi.system.domain.vo.SysOrderVo; import com.ruoyi.system.mapper.SysOrderMapper; import com.ruoyi.system.service.ISysOrderService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import java.util.List; import java.util.stream.Collectors; /** * 订单服务实现 */ @Service public class SysOrderServiceImpl implements ISysOrderService { @Autowired private SysOrderMapper orderMapper; /** * 查询订单列表 * Entity → Vo 转换 */ @Override public List<SysOrderVo> selectOrderList (SysOrderBo bo) { // 1. 构建查询条件（使用MyBatis-Plus的LambdaQueryWrapper） LambdaQueryWrapper<SysOrder> wrapper = Wrappers.lambdaQuery(); wrapper.like(StringUtils.isNotBlank(bo.getOrderNo()), SysOrder::getOrderNo, bo.getOrderNo()) .eq(bo.getStatus() != null , SysOrder::getStatus, bo.getStatus()) .between(bo.getBeginTime() != null && bo.getEndTime() != null , SysOrder::getCreateTime, bo.getBeginTime(), bo.getEndTime()); // 2. 查询数据库 List<SysOrder> list = orderMapper.selectList(wrapper); // 3. Entity → Vo 转换（使用Stream流处理） return list.stream() .map(entity -> BeanUtil.copyProperties(entity, SysOrderVo.class)) .collect(Collectors.toList()); } /** * 新增订单（带事务） */ @Override @Transactional(rollbackFor = Exception.class) public boolean insertOrder (SysOrder order) { // 业务逻辑处理 order.setOrderNo(generateOrderNo()); // 生成订单号 order.setCreateBy(SecurityUtils.getUsername()); // 设置创建人 // 插入数据库（MyBatis-Plus方法） return orderMapper.insert(order) > 0 ; } /** * 批量删除（带事务） */ @Override @Transactional(rollbackFor = Exception.class) public boolean deleteOrderByIds (Long[] orderIds) { // 使用MyBatis-Plus的批量删除 return orderMapper.deleteBatchIds(Arrays.asList(orderIds)) > 0 ; } /** * 生成订单号（业务逻辑） */ private String generateOrderNo () { return "ORD" + System.currentTimeMillis(); } } 规范2：Vue3 组合式 API (Composition API) 编码标准 核心原则： 所有新组件必须使用 <script setup lang="ts"> 语法糖 禁止使用 Options API（ export default {} ）编写新组件 优先使用 TypeScript 提供类型安全 响应式数据定义规范： ref() - 用于基本类型和单一对象引用 适用场景：字符串、数字、布尔值、单个对象引用 访问方式：通过 .value 访问/修改 模板中自动解包，无需 .value reactive() - 用于复杂对象和表单数据 适用场景：表单对象、查询参数、状态管理 特性：深度响应式，自动解包嵌套的ref 注意：解构会丢失响应性，需使用 toRefs() 转换 toRefs() - 保持解构后的响应性 使用场景：需要解构 reactive 对象时 作用：将 reactive 对象的每个属性转为 ref 组件通信规范： 父传子：defineProps（类型定义） // 使用 TypeScript 类型定义（推荐） interface Props { orderId : number ; orderData ?: SysOrder ; // 可选属性 } const props = defineProps< Props >(); // 或使用 withDefaults 定义默认值 const props = withDefaults (defineProps< Props >(), { orderData : () => ({}) }); 子传父：defineEmits（事件定义） // 定义事件类型 interface Emits { ( e : 'update:modelValue' , value : string ): void ; ( e : 'submit' , data : FormData ): void ; } const emit = defineEmits< Emits >(); // 触发事件 emit ( 'submit' , formData); 跨层级通信：provide/inject（谨慎使用） 仅用于深层组件树共享状态 优先使用 props/emits 保持数据流清晰 生命周期钩子： onMounted() - 组件挂载后（替代 mounted） onBeforeUnmount() - 组件卸载前（替代 beforeDestroy） onUpdated() - 组件更新后 watch() / watchEffect() - 侦听响应式数据变化 完整示例： <template> <div class="app-container"> <!-- 搜索栏 --> <el-form :model="queryParams" ref="queryFormRef" :inline="true" v-show="showSearch"> <el-form-item label="订单编号" prop="orderNo"> <el-input v-model="queryParams.orderNo" placeholder="请输入订单编号" clearable @keyup.enter="handleQuery" /> </el-form-item> <el-form-item label="订单状态" prop="status"> <el-select v-model="queryParams.status" placeholder="请选择订单状态" clearable> <el-option v-for="dict in sys_order_status" :key="dict.value" :label="dict.label" :value="dict.value" /> </el-select> </el-form-item> <el-form-item> <el-button type="primary" icon="Search" @click="handleQuery">搜索</el-button> <el-button icon="Refresh" @click="resetQuery">重置</el-button> </el-form-item> </el-form> <!-- 操作按钮 --> <el-row :gutter="10" class="mb8"> <el-col :span="1.5"> <el-button type="primary" plain icon="Plus" @click="handleAdd" v-hasPermi="['system:order:add']" >新增</el-button> </el-col> <el-col :span="1.5"> <el-button type="success" plain icon="Edit" :disabled="single" @click="handleUpdate" v-hasPermi="['system:order:edit']" >修改</el-button> </el-col> <el-col :span="1.5"> <el-button type="danger" plain icon="Delete" :disabled="multiple" @click="handleDelete" v-hasPermi="['system:order:remove']" >删除</el-button> </el-col> <right-toolbar v-model:showSearch="showSearch" @queryTable="getList"></right-toolbar> </el-row> <!-- 数据表格 --> <el-table v-loading="loading" :data="orderList" @selection-change="handleSelectionChange"> <el-table-column type="selection" width="55" align="center" /> <el-table-column label="订单编号" align="center" prop="orderNo" /> <el-table-column label="订单金额" align="center" prop="amount" /> <el-table-column label="订单状态" align="center" prop="status"> <template #default="scope"> <dict-tag :options="sys_order_status" :value="scope.row.status" /> </template> </el-table-column> <el-table-column label="创建时间" align="center" prop="createTime" width="180"> <template #default="scope"> <span>{{ parseTime(scope.row.createTime) }}</span> </template> </el-table-column> <el-table-column label="操作" align="center" class-name="small-padding fixed-width"> <template #default="scope"> <el-button type="text" icon="Edit" @click="handleUpdate(scope.row)" v-hasPermi="['system:order:edit']" >修改</el-button> <el-button type="text"