基于若依（RuoYi）框架的二次开发学习指南
基于若依（RuoYi）框架的二次开发学习指南：从入门到实战
若依（RuoYi）是目前国内非常流行的 Java 企业级快速开发框架。很多开发者在公司项目中会遇到基于若依进行二次开发的需求。本文将带你全面了解若依的技术栈、二次开发的核心模块，并提供学习路线与实战流程图，助你快速上手。
一、若依框架简介
若依（RuoYi）是一款基于 Spring Boot、Spring Security、MyBatis 和 Thymeleaf（或 Vue）的企业级快速开发平台，提供了代码生成器、权限管理、系统监控、日志管理等现成功能，大大减少了重复造轮子的工作。
目前主要分为两个版本：
- RuoYi（经典版）：前端使用 Thymeleaf + Bootstrap + jQuery，适合后端开发者快速构建管理后台。
- RuoYi-Vue：前后端分离，前端使用 Vue + Element UI，后端提供 RESTful API。
本文重点讨论RuoYi-Vue的二次开发，这是目前企业中最常用的版本。
二、若依的技术栈概览
| 层次 | 技术选型 | 说明 |
|---|---|---|
| 后端框架 | Spring Boot 2.x | 微服务风格，方便集成 |
| 安全框架 | Spring Security + JWT | 基于 token 的权限认证 |
| 持久层 | MyBatis Plus / MyBatis | 简化 CRUD，支持多数据源 |
| 数据库 | MySQL（支持 Oracle、SQL Server） | 动态切换 |
| 缓存 | Redis | 用于 token 存储、数据缓存 |
| 工具库 | Hutool、Fastjson、EasyExcel 等 | 提升开发效率 |
| 前端（Vue版） | Vue 2 / 3 + Element UI + Vuex + Vue Router | 单页应用 |
| 代码生成 | 自定义代码生成器 | 一键生成前后端 CRUD 代码 |
三、二次开发的典型场景及学习重点
二次开发通常指在若依已有功能基础上，新增业务模块或改造现有模块。主要涉及以下几个方面：
- 新建业务表 + 代码生成器使用
- 自定义接口开发（Controller、Service、Mapper）
- 权限控制（基于 @PreAuthorize 注解）
- 多数据源配置与切换
- 前端页面改造与菜单配置
- 工作流集成（若依自带简易工作流或扩展 Flowable）
下面逐一展开。
四、二次开发实战流程（附流程图）
4.1 总体流程
4.2 代码生成器使用详解
若依的代码生成器是其核心亮点，可以基于数据库表自动生成：
- 后端：Controller、Service、Mapper、Entity、XML 文件
- 前端：Vue 页面（列表、新增、编辑、查询）、API 接口定义
操作步骤：
- 在数据库创建业务表（遵循若依规范：主键为
id，建议包含create_by,create_time,update_by,update_time,del_flag等字段）。 - 登录若依管理后台 → 系统工具 → 代码生成 → 导入表。
- 编辑生成配置（树表、主子表、显示字段、查询条件等）。
- 点击“生成代码”并下载压缩包。
- 将生成的前端代码放入
src/views，后端代码放入对应包中。 - 运行 SQL 脚本（菜单 SQL）自动生成菜单权限。
4.3 自定义接口开发示例
假设我们需要新增一个“积分兑换记录”模块，除了代码生成的基础 CRUD，还需额外实现一个统计接口。
步骤：
- Mapper 接口：在对应的
Mapper.java中添加自定义方法。 - Mapper.xml：编写 SQL。
- Service 接口与实现：声明方法并实现。
- Controller：暴露 REST 接口，并添加权限注解。
@RestController@RequestMapping("/point/record")publicclassPointRecordController{@AutowiredprivateIPointRecordServicepointRecordService;@PreAuthorize("@ss.hasPermi('point:record:stat')")@GetMapping("/stat")publicAjaxResultstat(){returnAjaxResult.success(pointRecordService.getStatData());}}4.4 权限控制（Spring Security + JWT）
若依的权限基于 Spring Security，但通过自定义@PreAuthorize注解和@ss.hasPermi表达式简化了使用。
- 菜单权限：后台配置菜单，分配角色。
- 按钮级权限：前端通过
v-hasPermi指令控制显示/隐藏。
<el-button v-hasPermi="['point:record:add']" type="primary">新增</el-button>@PreAuthorize("@ss.hasPermi('point:record:add')")@PostMappingpublicAjaxResultadd(@RequestBodyPointRecordrecord){...}4.5 多数据源配置
若依支持动态数据源切换，常用于读写分离或连接不同业务库。
配置步骤：
- 在
application-druid.yml中定义多个数据源。 - 在需要使用非主数据源的 Service 方法上添加
@DataSource注解。
@ServicepublicclassOrderService{@DataSource(value=DataSourceType.SLAVE)publicList<Order>listOrders(){// 从从库查询}}五、学习路线与资源推荐
5.1 循序渐进学习路线图
5.2 官方资源
- 若依官网：http://ruoyi.vip
- RuoYi-Vue GitHub：https://gitee.com/y_project/RuoYi-Vue
- 文档：包含部署、开发手册、常见问题
5.3 二次开发常见问题与解决
| 问题 | 解决方案 |
|---|---|
| 代码生成后访问菜单空白 | 检查生成的 Vue 文件路由是否正确，以及后端 Controller 的@RequestMapping是否匹配 |
| 权限不足 403 | 检查角色是否分配了对应权限，@PreAuthorize表达式是否正确 |
| 多数据源事务失效 | 默认数据源为主库，如需跨库事务需手动编程式事务或使用分布式事务方案 |
| 前端请求报跨域 | 若依后端已配置跨域，检查 Nginx 或网关配置，确保前端代理正确 |
六、总结
若依是一个低门槛、高产出的快速开发框架，非常适合企业级后台管理系统的二次开发。通过学习若依，你可以：
- 掌握 Spring Boot + Vue 的实际项目整合
- 理解代码生成的原理并可以定制生成模板
- 熟练运用 RBAC 权限模型和 Spring Security
- 快速产出可用的业务模块，提升开发效率
二次开发的核心不是“完全依赖生成器”，而是在其基础上进行定制和优化。建议先完全跑通一个生成模块，再逐步深入改造源码，最后尝试自定义生成器模板，以适应不同业务场景。
最后送上一句话：用好若依，你的开发速度至少提升 50%；理解若依，你的架构能力将更上一层楼。