若依RuoYi-Vue前后端分离版从零到部署实战教程

1. 项目概述与核心价值最近在后台和社群里看到不少朋友在问关于若依RuoYi前后端分离版怎么上手、怎么部署、怎么二次开发的问题。作为一个在企业里用若依做过好几个中后台管理系统的老码农我觉得是时候系统地聊聊这个框架了。若依尤其是它的前后端分离版本可以说是国内Java开发者入门企业级后台管理系统的一个“标杆级”脚手架。它不像一些纯概念框架那样高高在上而是把权限管理、菜单管理、用户管理、部门管理、字典管理、操作日志这些后台系统里几乎100%会用到的功能全都给你做好了并且代码结构清晰文档也算齐全。你拿到手配置一下数据库改改前端页面就能快速搭出一个像模像样的管理后台把精力集中在自己的核心业务逻辑上。那么这个教程适合谁呢如果你是刚入行的Java后端或前端开发想找一个成熟的项目来学习企业级代码规范和架构或者你是中小团队的负责人需要快速启动一个后台管理项目但又不想从零开始造轮子亦或是你是个全栈爱好者想体验一下前后端分离项目如何协同工作。那么跟着这篇教程走一遍你不仅能跑起来一个若依项目更能理解它内部的运行机制知道在哪里改代码、加功能甚至能规避掉一些我当初踩过的坑。这篇内容我会尽量说人话把官方文档里语焉不详或者需要实际经验才能搞明白的地方都掰开揉碎了讲清楚。2. 环境准备与项目获取在开始敲代码之前把环境搭好是成功的一半。若依前后端分离版顾名思义后端和前端是两个独立的工程需要分别准备环境并启动。2.1 后端环境准备后端是基于Spring Boot的所以核心是Java环境。JDK官方推荐使用JDK 1.8。这是最稳定、兼容性最好的版本。我实测过JDK 11和17虽然大部分情况下也能运行但可能会遇到一些依赖库的兼容性问题尤其是涉及到一些老的第三方工具包时。对于新手强烈建议无脑选择JDK 1.8。去Oracle官网或者OpenJDK网站下载安装并配置好JAVA_HOME环境变量。在命令行输入java -version能正确显示版本信息就说明配置成功了。Maven这是Java项目的依赖管理和构建工具。若依使用Maven来管理它庞大的依赖库。你需要安装Maven并配置环境变量MAVEN_HOME同时将它的bin目录加入PATH。安装完成后在命令行输入mvn -v检查是否安装成功。国内网络环境访问Maven中央仓库可能较慢这里有一个非常重要的实操心得一定要配置国内镜像源。找到你的Maven安装目录下的conf/settings.xml文件在mirrors标签内添加阿里云的镜像配置这会让下载依赖的速度飞起避免卡在下载环节一两个小时。数据库若依默认支持MySQL。你需要安装MySQL 5.7或8.0版本。我推荐使用8.0性能和新特性更好。安装完成后记住你的数据库root密码。还需要一个数据库客户端工具比如Navicat、DBeaver或者MySQL Workbench用于执行SQL脚本和后续的数据查看。Redis若依使用Redis来存储会话Session信息、缓存数据等。这是必须安装的否则项目启动会报错。去Redis官网下载Windows版本如果你是Windows系统或者使用Linux包管理工具安装。安装后启动Redis服务。默认端口6379一般无需密码但生产环境一定要设密码开发工具后端代码开发IntelliJ IDEA是首选社区版就够用。它对Spring Boot的支持非常好能自动识别项目结构方便运行和调试。2.2 前端环境准备前端是基于Vue2和Element UI的。Node.js这是运行前端项目的JavaScript运行时环境。去Node.js官网下载LTS长期支持版本安装即可比如16.x或18.x。安装时会自动包含npmNode包管理器。安装后在命令行输入node -v和npm -v检查版本。开发工具前端代码编辑Visual Studio Code是绝配轻量且插件生态丰富。必备插件VeturVue语法高亮和提示、ESLint代码规范检查、Auto Close Tag自动闭合标签等。2.3 项目获取与初步了解环境齐备后我们来获取项目代码。获取代码访问若依的Gitee官方仓库搜索“RuoYi-Vue”直接下载ZIP包或者使用Git克隆。这是最稳妥的方式确保代码来源正宗。项目结构预览解压后你会看到两个主要文件夹ruoyi-admin这是后端Spring Boot项目的主模块启动类就在这里。ruoyi-ui这是前端Vue项目。 此外还有ruoyi-common通用工具类、ruoyi-framework框架核心、ruoyi-system系统模块等后端子模块结构非常清晰符合领域驱动的分包思想。导入数据库用你的数据库客户端连接MySQL创建一个新的数据库比如叫ry-vue。然后在后端项目的/sql目录下找到对应的SQL脚本文件通常有一个初始化脚本。在数据库中执行这个脚本它会创建所有的表并插入必要的初始数据如管理员账号admin/密码admin123、菜单数据、字典数据等。注意第一次导入时务必按顺序执行。通常脚本里会先删除已存在的表再创建。如果你的数据库里已经有同名表数据会被清空所以一定要在新库中操作。3. 后端启动与核心配置详解后端是整套系统的大脑我们先把它启动起来。3.1 关键配置文件解析用IDEA打开整个后端项目打开最外层的pom.xml所在目录。IDEA会自动识别为Maven项目并开始下载依赖如果之前配了镜像这里会很快。启动前必须修改几个核心配置文件它们都在ruoyi-admin模块的src/main/resources目录下。application.yml这是主配置文件。我们需要关注几个关键部分数据库连接找到datasource下的url、username、password。将url中的数据库名改为你刚才创建的如ry-vue用户名和密码改为你自己的MySQL配置。datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/ry-vue?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLtrueserverTimezoneGMT%2B8 username: root password: your_password_hereRedis配置找到redis部分确认host本地就是localhost、port默认6379。如果你的Redis设置了密码还需要配置password项。应用端口默认server.port是8080确保这个端口没有被其他程序占用。application-druid.yml这是数据库连接池Druid的专属配置。Druid是阿里开源的数据库连接池提供了强大的监控功能。这里通常不需要改但你可以看看初始连接数、最大连接数等配置后续性能调优时会用到。3.2 启动后端服务配置完成后在IDEA中找到ruoyi-admin模块下的RuoYiApplication类这就是Spring Boot的启动类。直接右键点击选择Run ‘RuoYiApplication‘。观察控制台日志如果没有报错最后看到类似Started RuoYiApplication in X.XXX seconds (JVM running for X.XXX)的日志并且有一行显示[http-nio-8080]之类的信息说明后端服务已经在8080端口成功启动。常见启动问题排查端口占用如果8080端口被占可以在application.yml中修改server.port为其他端口如8081。数据库连接失败检查application.yml中的数据库URL、用户名、密码是否正确数据库服务是否已启动。Redis连接失败检查Redis服务是否启动配置的端口和密码是否正确。依赖下载失败检查Maven镜像配置尝试在IDEA中右键项目 - Maven - Reload project。3.3 核心模块与代码结构理解启动成功后我们来快速浏览一下后端代码结构这对后续开发至关重要。ruoyi-admin启动入口和控制器层。controller包下的类定义了所有的API接口。比如SysLoginController处理登录SysUserController处理用户管理。这是你前后端对接时主要关注的包。ruoyi-system核心业务模块。包含了系统管理相关的所有业务逻辑是若依的精华所在。domain实体类对应数据库表。mapperMyBatis的映射接口定义了数据库操作方法。service及其impl业务逻辑层复杂的业务操作在这里实现。这个模块的代码结构是你编写自己业务模块的最佳范本。ruoyi-framework框架核心。包含了安全配置Spring Security、权限验证、通用工具、Web层封装等。比如SecurityConfig配置了如何拦截请求、如何验证权限。初期可以不用深究但要知道它是权限控制的基石。ruoyi-common通用工具。包含常量定义、工具类字符串处理、日期处理、类型转换等、异常定义等。这是你开发中会频繁调用的“工具箱”。理解这个结构后你就知道加一个新的业务功能比如“商品管理”通常是在ruoyi-system模块下仿照现有的“用户管理”、“部门管理”创建对应的domain、mapper、service、controller。而前端的请求最终是通过controller里的方法被处理的。4. 前端启动与项目结构剖析后端跑起来了现在让前端这个“面子工程”也动起来。4.1 安装依赖与启动用VS Code打开ruoyi-ui文件夹。打开终端Terminal。这里有一个关键步骤由于npm官方源在国内可能速度慢建议先切换为淘宝镜像源npm config set registry https://registry.npmmirror.com。在终端中运行npm install。这个命令会根据package.json文件下载项目所需的所有前端依赖包到node_modules目录。这个过程视网络情况可能需要几分钟。依赖安装完成后运行启动命令。查看package.json文件里的scripts部分你会看到“dev”: “vue-cli-service serve”。在终端运行npm run dev或yarn dev如果你用yarn。前端项目会启动一个开发服务器默认端口是80。控制台输出会告诉你访问地址通常是http://localhost。打开浏览器访问这个地址你应该能看到若依的登录界面。4.2 前端项目目录结构解析前端项目的结构决定了页面和组件如何组织理解它才能高效地修改和添加页面。public静态资源目录存放index.html和一些图标。src核心源代码目录。api非常重要这里存放所有调用后端API的JavaScript函数。每个文件通常对应一个后端模块如user.js对应SysUserController。你新增后端接口后需要在这里创建对应的函数。assets存放图片、样式等资源。components存放可复用的Vue组件比如上传组件、图表组件等。layout布局组件定义了整个页面的主体结构包括侧边栏、顶部导航、标签页等。router路由配置中心。index.js定义了所有页面的访问路径URL和对应的Vue组件。添加新页面后必须在这里注册路由。storeVuex状态管理用于全局共享数据如用户信息、权限信息。utils前端工具类如请求封装request.js它基于axios并统一处理了请求头、响应、错误等。views页面视图目录。这是你主要工作的地方。里面按模块分文件夹如system系统管理、monitor系统监控。每个Vue文件.vue就是一个页面。vue.config.jsVue项目的配置文件可以在这里配置代理、打包选项等。4.3 前后端联调与代理配置现在前端端口80和后端端口8080都运行了但它们是两个独立的服务存在跨域问题。若依前端已经配置好了开发环境下的代理帮你解决了这个问题。打开vue.config.js文件你会看到devServer配置项下的proxy设置。它把以/prod-api、/stage-api开头的请求代理到了后端的地址target: ‘http://localhost:8080‘。这就是为什么你在前端代码里看到API请求的URL是/prod-api/system/user/list但实际上请求被转发到了http://localhost:8080/system/user/list。这个机制意味着你在前端api目录下写请求路径时通常要加上这个代理前缀如/prod-api。这样在开发环境下请求才能正确转发到后端。而在生产环境构建时这些前缀可能会被替换或去除具体取决于你的部署配置。现在你可以在前端登录页使用默认账号admin和密码admin123登录。如果一切顺利你将进入若依的主控制台侧边栏有完整的菜单可以操作用户、角色、菜单等所有功能。至此一个完整的若依前后端分离项目就在你的本地运行起来了。5. 核心功能二次开发实战跑起来只是第一步更重要的是学会如何基于若依开发自己的功能。我们以一个最简单的“新闻公告管理”模块为例走一遍完整的增删改查流程。5.1 数据库设计与建表首先在后端数据库ry-vue中创建一张表。假设我们的新闻公告有ID、标题、内容、发布状态、创建时间等字段。CREATE TABLE sys_notice ( notice_id int NOT NULL AUTO_INCREMENT COMMENT 公告ID, notice_title varchar(255) NOT NULL COMMENT 公告标题, notice_content text COMMENT 公告内容, status char(1) DEFAULT 0 COMMENT 状态0正常 1关闭, create_by varchar(64) DEFAULT COMMENT 创建者, create_time datetime DEFAULT NULL COMMENT 创建时间, update_by varchar(64) DEFAULT COMMENT 更新者, update_time datetime DEFAULT NULL COMMENT 更新时间, remark varchar(500) DEFAULT NULL COMMENT 备注, PRIMARY KEY (notice_id) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4 COMMENT新闻公告表;注意字段命名风格与若依现有表保持一致如create_by,create_time这样能方便地复用若依的基类实体和通用逻辑。5.2 后端代码生成与编写若依提供了强大的代码生成器功能可以极大提升效率。但为了理解原理我们先手动创建。创建实体类在ruoyi-system模块的src/main/java/com/ruoyi/system/domain/下创建SysNotice.java。继承若依的BaseEntity类它已经包含了createBy,createTime等字段。public class SysNotice extends BaseEntity { private static final long serialVersionUID 1L; /** 公告ID */ private Long noticeId; /** 公告标题 */ private String noticeTitle; /** 公告内容 */ private String noticeContent; /** 状态0正常 1关闭 */ private String status; // 省略getter/setter方法 }创建Mapper接口和XML在ruoyi-system/src/main/java/com/ruoyi/system/mapper/下创建SysNoticeMapper.java接口。在resources/mapper/system/下创建SysNoticeMapper.xml文件编写SQL。这里可以直接仿照SysUserMapper来写。创建Service层在service包下创建ISysNoticeService接口及其实现类SysNoticeServiceImpl。实现基本的增删改查方法。创建Controller在ruoyi-admin/src/main/java/com/ruoyi/web/controller/system/下创建SysNoticeController.java。这是提供RESTful API的地方。你需要为列表查询、新增、修改、删除分别编写方法并使用PreAuthorize注解添加权限控制例如PreAuthorize(“ss.hasPermi(‘system:notice:list’)”)。实操心得Controller里的方法命名和URL设计尽量遵循若依的 REST 风格。例如获取列表用GET /system/notice/list新增用POST /system/notice修改用PUT /system/notice删除用DELETE /system/notice/{noticeIds}。权限字符串system:notice:xxx需要与后续在前端菜单配置的权限标识对应。5.3 前端页面开发后端API准备好了现在来制作前端页面。在views目录下创建模块文件夹例如src/views/system/notice。创建Vue页面文件在该文件夹下创建index.vue。这个文件通常包含三个部分template页面模板使用Element UI的组件搭建表单、表格、按钮等。scriptJavaScript逻辑这里会引入并调用我们在api目录下定义的函数处理数据绑定、表单提交、表格数据加载等。style页面样式。 你可以完全参考views/system/user/index.vue的写法它是标准的CRUD页面模板。在api目录下创建接口文件创建src/api/system/notice.js里面定义调用后端公告管理接口的函数例如listNotice,getNotice,addNotice,updateNotice,delNotice。每个函数使用封装好的request工具发送HTTP请求。注册路由打开src/router/index.js在constantRoutes或动态路由部分添加新页面的路由配置。需要指定路径path、名称name和组件component指向你刚创建的index.vue文件。5.4 菜单与权限配置页面做好了但怎么在侧边栏看到它并控制访问权限呢这需要进入系统管理后台进行配置。用管理员账号登录系统。进入【系统管理】-【菜单管理】。点击“新增”创建一个菜单。菜单名称新闻公告管理父菜单选择系统管理或其他你想放置的目录路由地址填写你在前端路由中配置的path例如/system/notice权限标识这个非常重要填写system:notice:view。这个标识需要和后端Controller方法上的PreAuthorize注解里的权限字符串前缀一致例如system:notice:list就包含了system:notice:view这个权限点。若依的权限验证是前缀匹配的。保存后刷新页面你应该能在侧边栏看到新加的“新闻公告管理”菜单点击即可进入你开发的页面。权限分配菜单只是入口具体的操作权限增、删、改、查需要通过角色来分配。进入【系统管理】-【角色管理】。编辑一个角色如“管理员”在“菜单权限”选项卡中勾选“新闻公告管理”菜单。在“权限标识”部分你会看到系统自动列出了该菜单下所有配置的权限标识如system:notice:view,system:notice:add等这些需要你在菜单管理或代码中明确定义。勾选你希望该角色拥有的操作权限。拥有该角色的用户登录后就只能进行其角色权限范围内的操作。例如如果只勾选了view那么用户只能查看列表无法看到新增、修改按钮。通过以上步骤一个具备完整权限控制的新功能模块就开发并集成完毕了。这个过程虽然步骤不少但每一步都有若依现有的模块作为参考模式非常固定熟练后开发效率会非常高。6. 生产环境部署指南本地开发调试没问题后最终需要部署到服务器上。前后端分离项目的部署是分开的。6.1 后端项目打包与部署打包在后端项目根目录有pom.xml的目录打开命令行执行mvn clean package。如果一切顺利会在ruoyi-admin/target目录下生成一个ruoyi-admin.jar文件。这就是可执行的Spring Boot应用包。注意打包前确保application.yml中的配置尤其是数据库和Redis连接信息已经修改为生产环境的地址和密码。通常我们会使用application-prod.yml文件来覆盖生产环境配置通过启动参数--spring.profiles.activeprod来激活。服务器准备准备一台Linux服务器如CentOS 7/8或Ubuntu安装好JDK 1.8、MySQL和Redis并确保防火墙开放了后端应用端口如8080和Redis端口6379。上传与运行将ruoyi-admin.jar上传到服务器。可以使用java -jar ruoyi-admin.jar直接运行但这样终端关闭程序就停了。推荐使用nohup或配置为systemd服务在后台运行。# 使用nohup后台运行并将日志输出到指定文件 nohup java -jar ruoyi-admin.jar --spring.profiles.activeprod app.log 21 使用ps -ef | grep java查看进程tail -f app.log查看实时日志。6.2 前端项目构建与部署构建在前端项目ruoyi-ui目录下运行npm run build:prod。这个命令会编译、压缩所有前端代码生成一个dist文件夹。里面的index.html和一堆静态文件JS, CSS, 图片就是最终产物。部署前端是纯静态文件需要用一个Web服务器来托管。最常见的是Nginx。在服务器上安装Nginx。将dist文件夹里的所有内容上传到Nginx的HTML目录例如/usr/share/nginx/html/。修改Nginx配置文件通常是/etc/nginx/nginx.conf或/etc/nginx/conf.d/default.conf。server { listen 80; # 监听80端口 server_name your-domain.com; # 你的域名或IP location / { root /usr/share/nginx/html; # 前端文件目录 index index.html index.htm; try_files $uri $uri/ /index.html; # 支持Vue Router的history模式 } # 关键配置反向代理将API请求转发到后端服务 location /prod-api/ { # 这个前缀需要和前端请求的baseURL一致 proxy_pass http://localhost:8080/; # 后端服务地址 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }重启Nginxsudo systemctl restart nginx。部署后的访问流程用户访问你的服务器IP或域名80端口Nginx返回前端页面。页面中的JavaScript发起API请求如/prod-api/system/user/listNginx根据配置将这个请求代理到运行在8080端口的后端Spring Boot应用。后端处理完请求返回数据给Nginx再由Nginx返回给浏览器。这样就完成了前后端分离的部署。7. 常见问题与深度优化技巧在实际使用和开发中你肯定会遇到各种各样的问题。这里我总结几个高频问题和一些进阶优化思路。7.1 高频问题排查速查表问题现象可能原因排查步骤与解决方案前端登录后跳转回登录页1. 后端Redis未启动或连接失败。2. 前后端分离导致Session/Cookie跨域问题。1. 检查Redis服务状态和配置。2. 检查后端SecurityConfig中关于跨域的配置CorsFilter。确保前端请求携带了正确的CookiewithCredentials: true。页面提示“没有操作权限”1. 当前登录用户的角色未分配该菜单或权限。2. 后端Controller方法上的PreAuthorize注解权限字符串与前端配置不符。3. 权限标识拼写错误。1. 去【角色管理】检查权限分配。2. 核对注解字符串如system:user:edit和菜单/权限配置是否一致。3. 注意大小写和冒号。代码生成器生成后页面报错或字段不对1. 数据库表设计不规范缺少必要字段。2. 生成时选择的模块、父菜单等配置错误。3. 生成后未清理浏览器缓存。1. 确保表有主键、有create_time,update_time等若依标准字段。2. 仔细核对生成器的每一个选项。3. 生成后重启前后端服务并强制刷新浏览器。前端npm install失败1. 网络问题npm源速度慢。2. Node.js版本不兼容。3. 磁盘权限不足。1. 切换npm镜像源到淘宝源。2. 使用nvm管理Node版本尝试切换LTS版本。3. 使用sudoLinux/Mac或以管理员身份运行终端Windows。后端打包mvn clean package失败1. Maven依赖下载失败。2. JDK版本不匹配。3. 本地代码编译错误。1. 检查Maven镜像配置尝试mvn clean compile先编译。2. 确认环境变量JAVA_HOME指向JDK 1.8。3. 根据控制台错误信息修复代码语法或依赖问题。7.2 性能与安全优化建议项目上线前以下几点值得关注数据库连接池调优在application-druid.yml中根据实际并发量调整initialSize初始连接数、maxActive最大活跃连接数、minIdle最小空闲连接数等参数。使用Druid自带的监控界面通常访问/druid/index.html需在配置中开启来观察SQL执行情况找出慢SQL进行优化。Redis缓存策略若依默认用Redis存Session。对于热点数据如字典数据、配置信息可以考虑主动缓存到Redis中减少数据库查询。在Service层使用Spring的Cacheable注解可以方便地实现。前端打包优化npm run build:prod默认配置已经做了不少优化。可以进一步通过分析打包报告npm run build:prod -- --report查看哪些依赖包体积过大考虑按需引入或使用CDN。使用压缩插件如compression-webpack-plugin生成.gz文件让Nginx直接发送压缩后的静态资源。API安全加固定期修改默认密码部署后第一件事就是修改admin用户的默认密码。限制登录尝试防止暴力破解可以在后端增加登录失败次数限制和锁定机制。HTTPS生产环境务必配置SSL证书启用HTTPS防止数据在传输中被窃听。输入验证与过滤虽然若依有基本的XSS过滤但在自己开发的业务接口中仍需对用户输入进行严格的校验和清理防止SQL注入和脚本攻击。日志与监控确保生产环境的日志配置得当logback-spring.xml将日志输出到文件并合理设置日志级别生产环境用INFO或WARN减少DEBUG输出。考虑集成Spring Boot Actuator提供健康检查端点或使用Prometheus Grafana搭建监控体系。7.3 个性化定制与扩展思路当基础功能满足后你可能会需要一些定制更换UI主题若依前端基于Element UI可以通过修改主题变量文件src/styles/variables.scss来更换主题色。也可以引入第三方Element UI的主题生成工具进行深度定制。集成工作流若依官方有分离版的RuoYi-Cloud版本集成了Activiti工作流。如果你需要审批流程可以参考其实现或者自行集成Flowable、Camunda等流程引擎。多数据源支持如果你的项目需要连接多个不同的数据库若依框架本身提供了多数据源支持的模块和示例配置相对复杂但文档和社区有相关讨论。前后端通信加密对于安全性要求极高的场景可以考虑对API请求和响应体进行非对称加密如RSA。这需要在前端加密数据后端解密处理再加密返回。这会显著增加系统复杂度和性能开销需谨慎评估。我个人在多次使用若依进行项目开发后最大的体会是它最大的价值不在于提供了多少开箱即用的功能而在于提供了一套经过大量项目验证的、标准的、易于理解和扩展的企业级代码架构和开发范式。你学会了在这个范式下添加一个“新闻公告”模块就等于学会了添加“商品管理”、“订单管理”等任何模块。遇到问题时多翻看若依已有的代码尤其是system模块下的用户、角色管理几乎你能想到的常见业务场景都能在那里找到参考实现。先模仿再理解最后创新这是学习若依乃至任何优秀开源框架的最佳路径。