1. RuoYi项目概述与核心价值
RuoYi是一款基于Spring Boot+Bootstrap的快速开发框架,在国内企业级应用开发领域有着广泛的应用基础。作为前后端分离架构的典型代表,它整合了Spring Security、MyBatis、Redis等主流技术栈,提供了完善的代码生成器和系统监控功能。我初次接触这个框架是在2018年参与某供应链管理系统开发时,当时就被其"开箱即用"的特性所吸引。
这个框架最大的优势在于它解决了企业级应用开发中的三个核心痛点:首先是权限管理模块的重复开发问题,RuoYi内置的RBAC权限模型已经覆盖了90%的中小型企业需求;其次是快速生成CRUD代码的能力,通过简单的配置就能自动生成前后端基础代码;最后是统一的技术栈约束,避免了团队技术选型的碎片化。根据我的项目经验,采用RuoYi框架能使常规管理系统的开发周期缩短40%左右。
2. 环境准备与工具选型
2.1 基础环境配置
在开始搭建前,需要确保开发环境满足以下要求:
- JDK 1.8+(推荐Amazon Corretto 11)
- MySQL 5.7+(注意字符集需设置为utf8mb4)
- Maven 3.6+(配置阿里云镜像加速依赖下载)
- Redis 5.0+(用于会话管理和缓存)
特别提醒:我曾遇到过因MySQL版本过高(8.0默认身份验证插件变更)导致的连接问题,解决方案是在my.cnf中添加default_authentication_plugin=mysql_native_password配置项。
2.2 开发工具推荐
根据团队协作经验,推荐以下工具组合:
- IDE:IntelliJ IDEA Ultimate(对Spring Boot支持最好)
- 数据库工具:DBeaver(跨平台)或Navicat
- API测试:Postman或国产的Apifox
- 版本控制:Git + GitLab/Gitee
注意:社区版IDEA对MyBatis插件支持有限,建议使用Ultimate版或安装Free MyBatis插件
3. 项目部署详细流程
3.1 源码获取与初始化
官方提供了两种获取方式:
- GitHub仓库:https://github.com/yangzongzhuan/RuoYi
- Gitee镜像:https://gitee.com/y_project/RuoYi
建议通过Git克隆方式获取代码:
bash复制git clone https://gitee.com/y_project/RuoYi.git
cd RuoYi
项目结构解析:
ruoyi-admin:主模块(包含启动类)ruoyi-common:通用工具类ruoyi-framework:框架核心ruoyi-system:系统模块ruoyi-quartz:定时任务ruoyi-generator:代码生成
3.2 数据库配置实战
- 创建数据库(字符集必须为utf8mb4):
sql复制CREATE DATABASE `ruoyi` CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
- 执行初始化SQL:
bash复制mysql -uroot -p ruoyi < sql/ry_20230223.sql
mysql -uroot -p ruoyi < sql/quartz.sql
常见问题处理:
- 若出现"Unknown collation"错误,检查MySQL版本是否低于5.5.3
- 表不存在错误通常是因为没有正确选择数据库
3.3 关键配置文件修改
- 数据库连接配置(
ruoyi-admin/src/main/resources/application-druid.yml):
yaml复制datasource:
master:
url: jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
username: root
password: 你的密码
- Redis配置(
application.yml):
yaml复制redis:
host: 127.0.0.1
port: 6379
password:
database: 0
- 验证码开关(经常被问到):
yaml复制# 在application.yml中
captcha:
enabled: false # 关闭验证码
4. 项目启动与验证
4.1 后端启动
- 编译项目:
bash复制mvn clean package -Dmaven.test.skip=true
- 运行主类:
- 在IDEA中直接运行
RuoYiApplication - 或使用命令行:
bash复制java -jar ruoyi-admin/target/ruoyi-admin.jar
启动成功后控制台会打印出Swagger地址和登录URL。
4.2 前端部署方案
RuoYi-Vue版本需要额外部署前端:
- 安装Node.js(建议14.x LTS版本)
- 安装依赖:
bash复制npm install --registry=https://registry.npmmirror.com
- 开发模式运行:
bash复制npm run dev
- 生产打包:
bash复制npm run build:prod
打包常见问题:
- 内存溢出:设置
NODE_OPTIONS=--max_old_space_size=4096 - 依赖冲突:删除node_modules后重新安装
- 跨域问题:配置
vue.config.js中的proxyTable
5. 系统配置与个性化
5.1 基础配置调整
- 修改系统名称:
properties复制# application.yml
ruoyi:
name: 你的系统名称
version: 1.0.0
- 文件上传路径配置:
yaml复制# application.yml
profile:
# 文件路径
path: /home/ruoyi/uploadPath
# 头像路径
avatar: /home/ruoyi/avatar
5.2 代码生成器使用技巧
- 配置数据源:
- 在"系统工具"→"代码生成"中配置表前缀
- 生成步骤:
- 选择表→生成代码→导入前端代码
- 高级技巧:
- 修改
vm模板文件可自定义生成代码风格 - 多表关联查询需要在生成的XML中手动添加
6. 生产环境部署要点
6.1 后端部署优化
- JVM参数调整(
start.sh):
bash复制JAVA_OPTS="-server -Xms2g -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m"
- 日志分割配置(logback-spring.xml):
xml复制<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<fileNamePattern>logs/ruoyi-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxFileSize>50MB</maxFileSize>
<maxHistory>30</maxHistory>
</rollingPolicy>
6.2 前端部署优化
- Nginx配置示例:
nginx复制server {
listen 80;
server_name yourdomain.com;
location / {
root /home/ruoyi/projects/ui;
index index.html index.htm;
try_files $uri $uri/ /index.html;
}
location /prod-api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
}
}
- 静态资源缓存策略:
nginx复制location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
expires 1y;
add_header Cache-Control "public, no-transform";
}
7. 常见问题排查指南
7.1 启动类问题
- 端口冲突:
text复制APPLICATION FAILED TO START
Description:
Web server failed to start. Port 8080 was already in use.
解决方案:
- 修改
server.port - 查找占用进程:
netstat -tunlp | grep 8080
- 数据库连接失败:
检查:
- 服务是否启动
- 用户名密码是否正确
- 时区参数是否添加(serverTimezone=GMT%2B8)
7.2 权限相关问题
- 菜单不显示:
- 检查角色权限分配
- 确认菜单状态是否为"显示"
- 清理浏览器缓存
- 接口403错误:
- 检查
@PreAuthorize注解权限字符串 - 确认用户角色是否拥有对应权限
7.3 验证码相关配置
彻底关闭验证码的完整步骤:
- 修改
application.yml:
yaml复制captcha:
enabled: false
- 修改前端
login.vue:
javascript复制// 注释掉验证码相关代码
// if (this.loginForm.captcha === "") {
// this.$modal.msgError("验证码不能为空");
// return;
// }
8. 扩展功能开发建议
8.1 集成第三方服务
- 短信服务集成:
- 阿里云短信SDK
- 配置
SmsConfigbean - 实现
ISmsService接口
- 支付对接:
- 支付宝/微信支付SDK
- 创建支付模块
- 添加回调处理
8.2 定制化开发
- 多数据源配置:
java复制@Configuration
@MapperScan(basePackages = "com.xxx.mapper", sqlSessionTemplateRef = "xxxSqlSessionTemplate")
public class XxxDataSourceConfig {
// 详细配置参考官方文档
}
- 自定义注解开发:
java复制@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DataScope {
String deptAlias() default "";
String userAlias() default "";
}
在实际项目开发中,我发现RuoYi的权限体系虽然完善,但在处理复杂业务权限时(如数据行级权限)需要额外开发。我的经验是在Service层添加自定义注解配合AOP实现,这样既能复用原有体系,又能满足特定业务需求。另外,对于高并发场景,建议对默认的Redis缓存策略进行优化,比如引入多级缓存或调整过期策略
