学习笔记ruoyi-vue-pro 源码分析

第十一章 · 搭建与复刻指南（从零跑起来 & 二次开发）

这是最后一章，也是一份行动手册。前面十章讲”是什么、为什么”，这一章讲”怎么把它跑起来、怎么基于它复刻一套自己的后台“。我从环境准备、数据库、配置、编译启动、前端对接、到”如何新增一个模块”，一步步展开；最后给一条”从零复刻一个业务模块”的最小闭环路径，把前面读到的 Builder → 存模型 → Engine 生成 真正用起来。

1. 总体流程

跑起来的关键是理解 三张图纸配合：

flowchart TD
    A[环境: JDK8 + Maven + MySQL + Redis] --> B[导入 ruoyi-vue-pro.sql 到 ruoyi-vue-pro 库]
    B --> C[改 application-*.yaml 的 数据源/Redis/tenant]
    C --> D[根 pom 确认启用 system+infra]
    D --> E[mvn 编译 yudao-server 并启动]
    E --> F[后端: 48080 起服务 + SQL 初始化]
    F --> G[前端: 配 VITE_BASE_API 启动对应 vue 工程]
    G --> H[登录 admin/admin123 → 在代码生成页建表生成业务]

一句话：Backend（yudao-server）负责接口，Frontend（独立 vue 仓库）负责界面，二者用 admin-api 前缀对接。

📌 环境适配说明：本仓库是 JDK8 + Spring Boot 2.7.18 分支（revision 2.4.2-jdk8-SNAPSHOT），用老版本 JDK/Maven 即可；若想用 JDK17 与 Boot3 走 master 的另一个分支。平台对国产数据库（达梦、人大金仓、openGauss、瀚高等）有专门的 SQL 与数据源适配，见下。

2. 环境准备

组件 版本建议 说明
JDK 1.8+ 本分支锁定
Maven 3.6+ 使用中央仓库；私有仓库可配镜像
MySQL 5.7 / 8.0 主数据库（可替换 Oracle/PG/达梦等，见 sql/ 下多方言）
Redis 5.0+ 缓存 + token 存储（第六章）

⚠️ Redis 必装：登录 token、权限缓存、租户缓存全部依赖 Redis。没有 Redis 时即使后端能起，登录也会因 token 存储失败而不可用。

3. 初始化数据库

sql/ 目录按六种数据库分门别类，每种含两个文件：

1
2
3
sql/mysql/
  ruoyi-vue-pro.sql   # 建库建表 + 全量字典/菜单/权限初始数据（48 张表）
  quartz.sql          # Quartz 定时任务的独立库表

步骤（以 MySQL 为例）：

1
2
3
mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS \`ruoyi-vue-pro\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -uroot -p ruoyi-vue-pro < sql/mysql/ruoyi-vue-pro.sql   # 主库
mysql -uroot -p ruoyi-vue-pro < sql/mysql/quartz.sql          # 定时任务表

ruoyi-vue-pro.sql 里 48 张表以 system_ 与 infra_ 前缀区分归属，正对应 第八章 的 system 与 第九章 的 infra 两个已启用模块。种子数据已含默认菜单（system_menu）、角色、字典与 admin 账号。

4. 配置文件

配置文件在 yudao-server/src/main/resources/，按 Profile 拆分：

文件 用途
application.yaml 公共配置：yudao.info.base-package、租户 ignore 列表、权限免登、MyBatis-Plus、Spring Cache
application-local.yaml 本地：端口 48080、dynamic-datasource primary: master、Redis 127.0.0.1:6379 db0
application-dev.yaml 开发环境

最需要改的三处：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# application-local.yaml 主数据源
spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/ruoyi-vue-pro?useUnicode=true&characterEncoding=utf8&...&nullable...
          username: root
          password: 你的密码
  redis:
    host: 127.0.0.1
    port: 6379          # Redis 默认无密码；若设了密码加 password

# 启动时选择 profile
bash> java -jar yudao-server.jar --spring.profiles.active=local

🔑 数据源用的是 **dynamic-datasource**（多数据源），primary: master 指定默认源。这也是 第五章 提到的”数据源适配、国产生信”的基础。

5. 编译与启动后端

1
2
3
4
5
6
7
cd ruoyi-vue-pro-master
mvn clean install -Dmaven.test.skip=true        # 先装 framework 与各 module 到本地仓
cd yudao-server
mvn spring-boot:run -Dspring.profiles.active=local
# 或打成 jar
mvn package -DskipTests
java -jar yudao-server/target/yudao-server.jar --spring.profiles.active=local

启动成功后看到 Started YudaoServerApplication，且 YudaoServerApplication.run（第十章）已装配 system+infra，即可访问 http://localhost:48080。

⚠️ **若某接口返回 501 “已禁用”**，表示它属于根 pom.xml 未启用的 module，需按提示引入该 module 的 <dependency> 并重建。

6. 前端对接

前端是独立仓库（本目录不包含）：官方有 yudao-ui-admin-vue2（Element UI）、yudao-ui-admin-vue3（Element Plus）、yudao-ui-admin-vben（vben）三套对应 第九章 的 CodegenFrontTypeEnum。首次对接：

1
2
3
4
5
6
# 以 Vue3 为例
cd yudao-ui-admin-vue3
npm install
# .env 里设置后端地址（本地就是 vite 代理）
VITE_BASE_API = http://127.0.0.1:48080
npm run dev

浏览器打开前端，用初始化账号登录：admin / admin123。登录后能看到 system 菜单：用户、角色、菜单、字典、部门等，全部来自 sql 种子数据。

7. 复刻一个最小业务模块（把前面章节用起来）

这是”复刻项目”最精华的一步——利用内置代码生成器，把”建表→生成→部署”压缩到几十分钟：

flowchart LR
    A[建业务表
例如 student] -->|√ 权限 infra:codegen| B[代码生成器
读取库表元数据]
    B -->|Builder 反推 DO/列| C[保存生成配置
infra_codegen_table/column]
    C -->|√ 权限 infra:codegen| D[Engine 渲染 .vm 模板]
    D -->|√ preview| E[预览 + 编辑 VO/Service]
    E -->|√ download| F[下载 zip 导入工程]
    F --> G[重启后端 + 刷新权限缓存]
    G --> H[前端菜单出现新增模块 CRUD 页]

最小步骤：

  1. 建库表：在 ruoyi-vue-pro 库建你想要的业务表（带 create_time/update_time/creator/updater/deleted 五个 BaseDO 字段，见 第五章）；
  2. 导入生成器：管理后台 → 基础设施 → 代码生成 → 从库表导入 student；
  3. 配置：选模块（如新建 system）与前端类型，Engine.execute 生成；
  4. 下载：把 Map<路径, 代码> 存成的 zip 导入 yudao-module-xxx 与前端仓库对应目录；
  5. 重启 + 清缓存：新 Controller 生效，登录后 system_menu 里配好权限即可在界面看到。

🔍 这一步把 第九章 的 CodegenBuilder(读元数据) → CodegenEngine(渲染) 整个用上了；生成的 Controller / Service / DO / Mapper 形态，正是 第五章 与 第八章 反复讲的标准分层长相。

8. 复刻项目的取舍清单

直接复刻（推荐给大多数场景）：

  • 保留 framework + system + infra 三件套：权限、多租户、日志、代码生成器免费获得；
  • 新增业务用代码生成器而非手写，保证分层与命名一致。

裁剪（轻量化）：

  • 去掉 multitenancy（把 yudao.tenant.enable 置 false）以省托盘与复杂度；
  • 关闭不要的前端框架（只留 FRONT_TEMPLATES 对应的一种）减少维护面。

扩展（进阶）：

  • 新模块照 第一章 的 -api/-biz 拆分，并在根 pom 启用；
  • 自定义数据权限规则继承 DataPermissionRule（第五章）实现行级隔离。

9. 故障排查速查

现象 最可能原因 定位
启动失败/找不到数据源 数据源 URL 或密码错、库未建 检查 application-local.yaml 的 master 段
登录报”验证码错误” 验证码接口被租户/免登误伤 确认 yudao.captcha.enable 与 ignore-urls
接口返回 501 走的 module 未启用 根 pom <modules> 补依赖（第十章）
多租户查询漏数据 表未继承 TenantBaseDO 或误入 ignore-tables 检查 DO 与 yudao.tenant.ignore-tables（第六章）
前端 401/403 token 未带 / 权限未配 检查 system_menu 按钮权限与 @ss.hasPermission（第四章、第八章）

10. 学习检查点

📝 本章小结

  • 环境 = JDK8 + Maven + MySQL + Redis；数据来自 sql/{数据库}/{主库,quartz}.sql。
  • 配置按 Profile 拆分，核心是 application-local.yaml 的数据源与 Redis。
  • 后端 mvn 编译启动 yudao-server；前端独立仓库用 VITE_BASE_API 对接，admin/admin123 登录。
  • 复刻最小闭环：建表 → 代码生成器导入 → 配置 → download → 导入工程 → 重启部署。
  • 模块启用/裁剪由根 pom 决定，未启用模块由 DefaultController 返回 501。

🤔 思考题

  1. 为什么 ruoyi-vue-pro.sql 里已经含菜单、角色、字典的种子数据，前端登录后才有界面？（提示：RBAC 的 system_menu 是权限 + 动态路由来源）

    参考答案

    前端的动态路由与按钮权限都来自后端 get-permission-info 接口（第七章），它把 用户→角色→菜单→permission 串返回给前端。若 system_menu 没有种子菜单，登录后 getPermissionInfo 拿不到菜单，前端就渲染不出任何管理页面。所以 SQL 必须预置菜单/角色/字典，前端才有东西可显示。

  2. 若前端是 vben 而你在 application.yaml 把 front-type 配成了 Vue3 Element Plus，CodegenEngine 会怎样？（提示：FRONT_TEMPLATES.row(frontType)）

    参考答案

    getTemplates 用 FRONT_TEMPLATES.row(frontType) 取对应”行”。若 front-type 配成 Vue3(Element Plus)，则只取该行模板，生成的是 yudao-ui-admin-vue3 目录结构的代码；vben 前端导入这些代码会导致语法/目录对不上编译失败。因此 front-type 必须与你实际使用的前端框架一致，否则生成的前端代码无法直接用。

  3. 你新加的表继承了 TenantBaseDO，但查询却没被按租户过滤，最可能两个原因是什么？（提示：[]ignore-tables 配置、DO 变更后 MyBatis 映射）

    参考答案

    ①表名被误加进 yudao.tenant.ignore-tables（全局豁免导致不过滤）；②新增表后未重新编译/重启，MyBatis-Plus 的租户拦截器拿到的仍是旧映射或表名带前后缀不匹配 ignoreTable 判断（第六章 的 TargetTable 规则）。检查这两处即可定位。

至此整部文档结束。下一篇：参考资料索引 →