从零到一基于若依框架的实战项目搭建与二次开发指南在当今快速迭代的软件开发领域选择一个成熟稳定的框架作为项目基础能够显著提升开发效率和系统稳定性。若依RuoYi作为国内广泛使用的开源企业级开发框架集成了Spring Boot、MyBatis、Vue.js等主流技术栈提供了一套完整的权限管理体系和代码生成工具特别适合快速构建中后台管理系统。本文将带您从零开始深入探索若依框架的实战应用全流程。1. 环境准备与项目初始化搭建若依开发环境是项目启动的第一步。不同于简单的下载即用合理的环境配置能为后续开发避免许多潜在问题。基础软件要求JDK 1.8推荐Amazon Corretto 11MySQL 5.7注意字符集设置为utf8mb4Redis 5.0用于会话管理和缓存Node.js 14.x前端构建环境Maven 3.6Java依赖管理提示在Windows环境下建议使用Docker部署MySQL和Redis可以避免本地安装的版本冲突问题。项目初始化有两种推荐方式# 方式一从Gitee克隆官方仓库 git clone https://gitee.com/y_project/RuoYi-Vue.git cd RuoYi-Vue # 方式二使用官方初始化脚本适合定制化需求 curl -s https://gitee.com/y_project/RuoYi-Vue/raw/master/init.sh | bash后端项目启动前需要完成以下配置创建MySQL数据库字符集必须为utf8mb4执行项目SQL脚本位于sql/目录修改ruoyi-admin/src/main/resources/application-druid.yml中的数据库连接信息配置Redis连接参数application.yml启动顺序建议# 先启动Redis服务 redis-server --daemonize yes # 然后启动后端Spring Boot应用 cd ruoyi-admin mvn spring-boot:run # 最后启动前端开发服务器 cd ruoyi-ui npm install npm run dev常见问题排查表问题现象可能原因解决方案启动时报数据库连接错误1. 数据库服务未运行2. 账号权限不足3. 字符集不匹配1. 检查MySQL服务状态2. 验证账号密码3. 确认数据库为utf8mb4前端编译失败1. Node版本不兼容2. 依赖下载不全1. 使用nvm切换Node版本2. 删除node_modules后重新install接口404错误1. 后端未启动2. 跨域配置问题1. 检查后端日志2. 确认proxy配置正确2. 核心功能模块深度解析若依框架内置了企业级应用所需的常见功能模块理解这些模块的设计原理对二次开发至关重要。2.1 权限控制系统剖析若依采用RBAC基于角色的访问控制模型但在实现上做了多层抽象用户-角色-菜单三级权限体系数据权限细粒度控制支持部门数据隔离操作权限通过注解实现如PreAuthorize权限数据结构关系// 典型权限注解使用示例 RestController RequestMapping(/system/user) public class UserController { PreAuthorize(ss.hasPermi(system:user:list)) GetMapping(/list) public TableDataInfo list(SysUser user) { // 查询逻辑 } Log(title 用户管理, businessType BusinessType.UPDATE) PreAuthorize(ss.hasPermi(system:user:edit)) PostMapping(/edit) public AjaxResult edit(Validated RequestBody SysUser user) { // 更新逻辑 } }权限控制的核心表包括sys_user用户基础信息sys_role角色定义sys_menu菜单及权限标识sys_user_role用户角色关联sys_role_menu角色菜单关联2.2 代码生成器实战技巧若依的代码生成器是其最具特色的功能之一能自动生成前后端基础CRUD代码。高级用法包括主子表关联生成配置外键关系后自动生成关联操作模板定制修改resources/vm下的Velocity模板字段类型映射在generator.yml中配置特殊字段处理典型生成流程# 1. 准备数据库表 CREATE TABLE biz_product ( id bigint NOT NULL AUTO_INCREMENT, name varchar(255) NOT NULL COMMENT 产品名称, price decimal(10,2) DEFAULT NULL COMMENT 售价, status char(1) DEFAULT 0 COMMENT 状态0正常 1停用, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT产品表; # 2. 在系统管理-代码生成中导入表 # 3. 配置生成选项包路径、模块名等 # 4. 下载代码并导入对应模块生成后的代码需要手动集成到项目中将Java代码放入对应包路径Vue文件放入src/views目录添加路由配置src/router/index.js配置菜单权限3. 项目架构与源码分析理解若依的模块化设计对二次开发和系统维护至关重要。3.1 后端项目结构解析ruoyi ├── ruoyi-admin // 核心启动模块Spring Boot入口 ├── ruoyi-common // 通用工具类库 │ ├── annotation // 自定义注解 │ ├── config // 公共配置 │ ├── utils // 工具包 │ └── xss // XSS过滤组件 ├── ruoyi-framework // 框架核心 │ ├── aspectj // AOP切面 │ ├── config // 核心配置 │ ├── datasource // 数据源管理 │ └── web // Web层通用处理 └── ruoyi-system // 系统模块业务代码示例模块依赖关系ruoyi-admin→ruoyi-system→ruoyi-framework→ruoyi-common新增业务模块应参照ruoyi-system结构3.2 前端架构设计若依前端采用Vue3Element Plus技术栈关键设计特点API请求封装src/api目录下的统一请求处理状态管理Pinia替代Vuex的轻量级方案动态路由根据权限动态生成路由表组件封装通用组件位于src/components前端与后端的交互流程页面发起请求带Token前端代理处理vite.config.js中的proxy配置后端拦截器验证JwtAuthenticationTokenFilter权限注解检查PreAuthorizeAspect返回JSON数据4. 二次开发实战指南基于若依进行二次开发时需要遵循一定的规范以保证项目可维护性。4.1 创建新业务模块推荐使用Maven多模块方式新增业务功能在父pom.xml中添加模块声明modules moduleruoyi-admin/module moduleruoyi-common/module moduleruoyi-framework/module moduleruoyi-system/module moduleruoyi-custom/module !-- 新增模块 -- /modules创建新模块并配置依赖!-- ruoyi-custom/pom.xml -- dependencies dependency groupIdcom.ruoyi/groupId artifactIdruoyi-common/artifactId /dependency !-- 其他必要依赖 -- /dependencies在admin模块中添加对新模块的依赖!-- ruoyi-admin/pom.xml -- dependency groupIdcom.ruoyi/groupId artifactIdruoyi-custom/artifactId /dependency4.2 深度定制化改造案例集成OSS文件存储添加阿里云OSS SDK依赖dependency groupIdcom.aliyun.oss/groupId artifactIdaliyun-sdk-oss/artifactId version3.15.1/version /dependency创建配置类Configuration public class OssConfig { Value(${oss.endpoint}) private String endpoint; Value(${oss.accessKeyId}) private String accessKeyId; Value(${oss.accessKeySecret}) private String accessKeySecret; Value(${oss.bucketName}) private String bucketName; Bean public OSS ossClient() { return new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret); } }改造文件上传服务Service public class OssFileService { Autowired private OSS ossClient; public String upload(MultipartFile file, String path) { try { InputStream inputStream file.getInputStream(); ossClient.putObject(bucketName, path, inputStream); return String.format(https://%s.%s/%s, bucketName, endpoint, path); } catch (IOException e) { throw new ServiceException(文件上传失败); } } }前端适配改造// 修改src/api/system/user.js中的上传接口 export function uploadAvatar(data) { return request({ url: /system/user/profile/avatar, method: post, data: data, headers: { Content-Type: multipart/form-data } }) }4.3 界面个性化定制若依前端支持多种自定义方式主题换肤修改src/styles/variables.scss中的主题变量布局调整编辑src/layout/components下的布局组件图标替换使用阿里图标库资源替换src/assets/icons/svg登录页定制修改src/views/login.vue组件关键配置文件src/settings.js系统全局配置src/store/modules/settings.js布局设置存储src/styles/element-ui.scssElement Plus样式覆盖5. 性能优化与生产部署项目开发完成后合理的优化和部署方案能显著提升系统稳定性。5.1 前端优化策略代码压缩启用Vite的生产构建模式npm run buildCDN加速配置externals减少打包体积// vite.config.js export default defineConfig({ build: { rollupOptions: { external: [vue, element-plus], output: { globals: { vue: Vue, element-plus: ElementPlus } } } } })异步加载路由组件动态导入// src/router/index.js const routes [ { path: /system/user, component: () import(/views/system/user), hidden: true } ]5.2 后端性能调优数据库优化添加必要的索引配置连接池参数druid# application-druid.yml spring: datasource: druid: initial-size: 5 max-active: 20 min-idle: 5缓存策略热点数据使用Redis缓存配置合理的缓存过期时间Cacheable(key user: #userId, cacheNames userCache, unless #result null) public User getUserById(Long userId) { return userMapper.selectById(userId); }日志优化使用Logback异步日志按级别分离日志文件5.3 容器化部署方案推荐使用Docker Compose进行生产部署# docker-compose.yml version: 3 services: mysql: image: mysql:5.7 environment: MYSQL_ROOT_PASSWORD: ruoyi123 MYSQL_DATABASE: ruoyi volumes: - ./mysql/data:/var/lib/mysql - ./mysql/conf:/etc/mysql/conf.d ports: - 3306:3306 redis: image: redis:6 command: redis-server --appendonly yes volumes: - ./redis/data:/data ports: - 6379:6379 backend: build: ./ruoyi-admin depends_on: - mysql - redis ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod frontend: build: ./ruoyi-ui ports: - 80:80构建和启动命令# 构建镜像 docker-compose build # 启动服务 docker-compose up -d # 查看日志 docker-compose logs -f在实际项目开发中我们发现合理的模块划分和清晰的接口定义能显著提升团队协作效率。建议在复杂业务场景下采用领域驱动设计DDD的思想来组织代码结构将业务逻辑集中在领域层保持应用层的轻薄。
从零到一：基于若依框架的实战项目搭建与二次开发指南
发布时间：2026/6/17 23:24:04
从零到一基于若依框架的实战项目搭建与二次开发指南在当今快速迭代的软件开发领域选择一个成熟稳定的框架作为项目基础能够显著提升开发效率和系统稳定性。若依RuoYi作为国内广泛使用的开源企业级开发框架集成了Spring Boot、MyBatis、Vue.js等主流技术栈提供了一套完整的权限管理体系和代码生成工具特别适合快速构建中后台管理系统。本文将带您从零开始深入探索若依框架的实战应用全流程。1. 环境准备与项目初始化搭建若依开发环境是项目启动的第一步。不同于简单的下载即用合理的环境配置能为后续开发避免许多潜在问题。基础软件要求JDK 1.8推荐Amazon Corretto 11MySQL 5.7注意字符集设置为utf8mb4Redis 5.0用于会话管理和缓存Node.js 14.x前端构建环境Maven 3.6Java依赖管理提示在Windows环境下建议使用Docker部署MySQL和Redis可以避免本地安装的版本冲突问题。项目初始化有两种推荐方式# 方式一从Gitee克隆官方仓库 git clone https://gitee.com/y_project/RuoYi-Vue.git cd RuoYi-Vue # 方式二使用官方初始化脚本适合定制化需求 curl -s https://gitee.com/y_project/RuoYi-Vue/raw/master/init.sh | bash后端项目启动前需要完成以下配置创建MySQL数据库字符集必须为utf8mb4执行项目SQL脚本位于sql/目录修改ruoyi-admin/src/main/resources/application-druid.yml中的数据库连接信息配置Redis连接参数application.yml启动顺序建议# 先启动Redis服务 redis-server --daemonize yes # 然后启动后端Spring Boot应用 cd ruoyi-admin mvn spring-boot:run # 最后启动前端开发服务器 cd ruoyi-ui npm install npm run dev常见问题排查表问题现象可能原因解决方案启动时报数据库连接错误1. 数据库服务未运行2. 账号权限不足3. 字符集不匹配1. 检查MySQL服务状态2. 验证账号密码3. 确认数据库为utf8mb4前端编译失败1. Node版本不兼容2. 依赖下载不全1. 使用nvm切换Node版本2. 删除node_modules后重新install接口404错误1. 后端未启动2. 跨域配置问题1. 检查后端日志2. 确认proxy配置正确2. 核心功能模块深度解析若依框架内置了企业级应用所需的常见功能模块理解这些模块的设计原理对二次开发至关重要。2.1 权限控制系统剖析若依采用RBAC基于角色的访问控制模型但在实现上做了多层抽象用户-角色-菜单三级权限体系数据权限细粒度控制支持部门数据隔离操作权限通过注解实现如PreAuthorize权限数据结构关系// 典型权限注解使用示例 RestController RequestMapping(/system/user) public class UserController { PreAuthorize(ss.hasPermi(system:user:list)) GetMapping(/list) public TableDataInfo list(SysUser user) { // 查询逻辑 } Log(title 用户管理, businessType BusinessType.UPDATE) PreAuthorize(ss.hasPermi(system:user:edit)) PostMapping(/edit) public AjaxResult edit(Validated RequestBody SysUser user) { // 更新逻辑 } }权限控制的核心表包括sys_user用户基础信息sys_role角色定义sys_menu菜单及权限标识sys_user_role用户角色关联sys_role_menu角色菜单关联2.2 代码生成器实战技巧若依的代码生成器是其最具特色的功能之一能自动生成前后端基础CRUD代码。高级用法包括主子表关联生成配置外键关系后自动生成关联操作模板定制修改resources/vm下的Velocity模板字段类型映射在generator.yml中配置特殊字段处理典型生成流程# 1. 准备数据库表 CREATE TABLE biz_product ( id bigint NOT NULL AUTO_INCREMENT, name varchar(255) NOT NULL COMMENT 产品名称, price decimal(10,2) DEFAULT NULL COMMENT 售价, status char(1) DEFAULT 0 COMMENT 状态0正常 1停用, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT产品表; # 2. 在系统管理-代码生成中导入表 # 3. 配置生成选项包路径、模块名等 # 4. 下载代码并导入对应模块生成后的代码需要手动集成到项目中将Java代码放入对应包路径Vue文件放入src/views目录添加路由配置src/router/index.js配置菜单权限3. 项目架构与源码分析理解若依的模块化设计对二次开发和系统维护至关重要。3.1 后端项目结构解析ruoyi ├── ruoyi-admin // 核心启动模块Spring Boot入口 ├── ruoyi-common // 通用工具类库 │ ├── annotation // 自定义注解 │ ├── config // 公共配置 │ ├── utils // 工具包 │ └── xss // XSS过滤组件 ├── ruoyi-framework // 框架核心 │ ├── aspectj // AOP切面 │ ├── config // 核心配置 │ ├── datasource // 数据源管理 │ └── web // Web层通用处理 └── ruoyi-system // 系统模块业务代码示例模块依赖关系ruoyi-admin→ruoyi-system→ruoyi-framework→ruoyi-common新增业务模块应参照ruoyi-system结构3.2 前端架构设计若依前端采用Vue3Element Plus技术栈关键设计特点API请求封装src/api目录下的统一请求处理状态管理Pinia替代Vuex的轻量级方案动态路由根据权限动态生成路由表组件封装通用组件位于src/components前端与后端的交互流程页面发起请求带Token前端代理处理vite.config.js中的proxy配置后端拦截器验证JwtAuthenticationTokenFilter权限注解检查PreAuthorizeAspect返回JSON数据4. 二次开发实战指南基于若依进行二次开发时需要遵循一定的规范以保证项目可维护性。4.1 创建新业务模块推荐使用Maven多模块方式新增业务功能在父pom.xml中添加模块声明modules moduleruoyi-admin/module moduleruoyi-common/module moduleruoyi-framework/module moduleruoyi-system/module moduleruoyi-custom/module !-- 新增模块 -- /modules创建新模块并配置依赖!-- ruoyi-custom/pom.xml -- dependencies dependency groupIdcom.ruoyi/groupId artifactIdruoyi-common/artifactId /dependency !-- 其他必要依赖 -- /dependencies在admin模块中添加对新模块的依赖!-- ruoyi-admin/pom.xml -- dependency groupIdcom.ruoyi/groupId artifactIdruoyi-custom/artifactId /dependency4.2 深度定制化改造案例集成OSS文件存储添加阿里云OSS SDK依赖dependency groupIdcom.aliyun.oss/groupId artifactIdaliyun-sdk-oss/artifactId version3.15.1/version /dependency创建配置类Configuration public class OssConfig { Value(${oss.endpoint}) private String endpoint; Value(${oss.accessKeyId}) private String accessKeyId; Value(${oss.accessKeySecret}) private String accessKeySecret; Value(${oss.bucketName}) private String bucketName; Bean public OSS ossClient() { return new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret); } }改造文件上传服务Service public class OssFileService { Autowired private OSS ossClient; public String upload(MultipartFile file, String path) { try { InputStream inputStream file.getInputStream(); ossClient.putObject(bucketName, path, inputStream); return String.format(https://%s.%s/%s, bucketName, endpoint, path); } catch (IOException e) { throw new ServiceException(文件上传失败); } } }前端适配改造// 修改src/api/system/user.js中的上传接口 export function uploadAvatar(data) { return request({ url: /system/user/profile/avatar, method: post, data: data, headers: { Content-Type: multipart/form-data } }) }4.3 界面个性化定制若依前端支持多种自定义方式主题换肤修改src/styles/variables.scss中的主题变量布局调整编辑src/layout/components下的布局组件图标替换使用阿里图标库资源替换src/assets/icons/svg登录页定制修改src/views/login.vue组件关键配置文件src/settings.js系统全局配置src/store/modules/settings.js布局设置存储src/styles/element-ui.scssElement Plus样式覆盖5. 性能优化与生产部署项目开发完成后合理的优化和部署方案能显著提升系统稳定性。5.1 前端优化策略代码压缩启用Vite的生产构建模式npm run buildCDN加速配置externals减少打包体积// vite.config.js export default defineConfig({ build: { rollupOptions: { external: [vue, element-plus], output: { globals: { vue: Vue, element-plus: ElementPlus } } } } })异步加载路由组件动态导入// src/router/index.js const routes [ { path: /system/user, component: () import(/views/system/user), hidden: true } ]5.2 后端性能调优数据库优化添加必要的索引配置连接池参数druid# application-druid.yml spring: datasource: druid: initial-size: 5 max-active: 20 min-idle: 5缓存策略热点数据使用Redis缓存配置合理的缓存过期时间Cacheable(key user: #userId, cacheNames userCache, unless #result null) public User getUserById(Long userId) { return userMapper.selectById(userId); }日志优化使用Logback异步日志按级别分离日志文件5.3 容器化部署方案推荐使用Docker Compose进行生产部署# docker-compose.yml version: 3 services: mysql: image: mysql:5.7 environment: MYSQL_ROOT_PASSWORD: ruoyi123 MYSQL_DATABASE: ruoyi volumes: - ./mysql/data:/var/lib/mysql - ./mysql/conf:/etc/mysql/conf.d ports: - 3306:3306 redis: image: redis:6 command: redis-server --appendonly yes volumes: - ./redis/data:/data ports: - 6379:6379 backend: build: ./ruoyi-admin depends_on: - mysql - redis ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod frontend: build: ./ruoyi-ui ports: - 80:80构建和启动命令# 构建镜像 docker-compose build # 启动服务 docker-compose up -d # 查看日志 docker-compose logs -f在实际项目开发中我们发现合理的模块划分和清晰的接口定义能显著提升团队协作效率。建议在复杂业务场景下采用领域驱动设计DDD的思想来组织代码结构将业务逻辑集中在领域层保持应用层的轻薄。
