帝可得这个开发代号最初只是我任务清单里一行不起眼的字。直到需求文档发下来才知道背后是一套完整的客户权益积分兑换系统用户在前台签到、做任务、消费换积分再用积分换优惠券、实物商品或者参与抽奖后台则要支撑会员管理、积分账户、商品库存、兑换订单、活动配置。这类系统绕不开用户权限、组织架构、菜单字典这些基础能力与其从零手写不如直接选一个成熟的 Java 快速开发平台把骨架搭起来我选的是 RuoYi若依这也是整个搭建工作的核心关键词。系列第一篇也就是本文只干一件事把 RuoYi 跑起来打通登录、权限、菜单、代码生成这条链路给帝可得后续的积分、会员、商品、订单模块打好底座。这篇文章适合用过 Spring Boot、但没接触过快速开发平台的 Java 开发者也适合准备在团队内推广若依做二次开发的朋友。看完你可以复现出一个能登录、能管用户、能跑代码生成的可运行后台后续模块开发全部基于这套骨架展开。1. 项目背景与整体认知这个帝可得到底要做什么1.1 项目定位与业务愿景帝可得这个名字第一次出现在我面前时我以为是随手起的代号后来顺着需求文档梳理才发现它承载的是一个典型的 B 端管理加 C 端用户场景C 端用户在小程序或 App 里完成签到、邀请、消费等行为获得积分积分进入个人账户用户再在积分商城里消耗积分兑换商品或优惠券运营人员则在后台配置活动、管理商品库存、审核兑换订单、处理积分流水。这种架构听起来不复杂但真正动手写代码之前要算一笔账。用户管理、角色权限、部门组织、菜单路由、操作日志、字典管理这些每个后台系统都长差不多的基础能力纯手写大概要占掉项目一半的工作量而且很难写得比成熟方案更严谨。与其在基础设施上重复造轮子不如把精力全部放到帝可得自己的业务逻辑上比如积分公式怎么算兑换流程怎么防超卖订单状态机怎么设计这些才是决定项目成败的地方。所以我的规划很明确整个系列按阶段推进第一篇搭建骨架让平台跑起来第二篇梳理权限模型把角色的数据权限范围定清楚之后再逐个落地会员、商品、积分账户、兑换订单这些业务模块。每一篇只解决一个阶段的问题不贪多这也是帝可得-1这个编号的含义。你在看这篇文章时如果目的是搭建一个属于自己的若依项目完全可以把它当作标准操作手册来用业务方向不同不影响底层步骤。1.2 为什么选择 RuoYi 作为基座Java 生态里快速开发平台不少选 RuoYi 而不是别的我当时是认真对比过的。第一条理由是技术栈足够主流Spring Boot 做基础框架Spring Security 做认证授权JWT 做无状态登录MyBatis 做数据持久化Druid 做连接池这些都是国内后端团队最常见的组合不会出现平台很强大但没人会维护的尴尬。团队招人、接手、运维都相对容易。第二条是前后端分离的形态足够成熟。RuoYi-Vue 默认带一套 Vue Element UI 的后台前端菜单、路由、按钮权限全部是后端动态下发前端根据当前用户权限过滤生成页面用户拿到就能登录用起来。这一点对于帝可得这种管理后台需求非常贴合省去了大量前端基础设施的搭建时间。第三条是生态和周边工具完整。尤其是代码生成器我后面会专门讲它几乎就是为这种表格型业务模块定制的数据库建好表生成器扫描到表结构自动产出后端增删改查代码、前端列表页和表单页开发速度是手写的数倍。另外RuoYi 还内置了定时任务、多数据源、操作日志、通知公告等功能很多 CRM、ERP 类项目可以直接拿这些能力做二次开发。也有人说你们项目又不复杂直接用 Spring Boot 官方脚手架不是更干净吗。官方脚手架的优势是零冗余但代价是菜单、权限、登录态、安全策略这些都要自己设计自己实现帝可得的管理后台没有那么多需要特殊定制的场景直接用成熟的样板间更划算。就好比装修官方脚手架是毛坯房RuoYi 是精装样板间后者的初始成本高一点但拎包入住的速度远超前者。1.3 版本选型为什么用 RuoYi-VueRuoYi 官方有多种项目形态这也是新手容易懵的第一个地方。总结起来大概有四条线前后端不分离的单体应用、前后端分离的 RuoYi-Vue、微服务版本的 RuoYi-Cloud以及基于 Vue3 的 RuoYi-Vue3。帝可得第一期我选的是 RuoYi-Vue。理由很朴素项目的业务量级和团队规模都没到需要微服务的地步直接上 RuoYi-Cloud 意味着要同时处理 Nacos、Gateway、多个服务实例的运维问题环境复杂度反而会把开发节奏拖垮。而单应用形态虽然部署最简单前后端代码耦合在一起以后如果前端要独立成组、单独打包就会比较被动。折中的 RuoYi-Vue 最适合当前阶段后端保持单体部署的简单前端独立构建后续真到了拆服务的时刻RuoYi 社区在这个方向上的实践资料也最丰富迁移有迹可循。这里有一个细节值得专门说RuoYi-Vue 老版本是 Vue2 Element UIRuoYi-Vue3 则是 Vue3 Element Plus。如果你所在团队对 Vue2 非常熟用 Vue2 版本文档最齐全、踩坑记录最多如果是全新团队、全新项目直接用 Vue3 版本更符合现在前端生态的趋势。我们这边是团队整体从 Vue2 迁移过来的为了减少学习成本选了 Vue2 版这篇文章里涉及的前端操作命令两个版本基本通用遇到细微差异我会单独提醒。2. 搭建前的环境准备与工具链2.1 开发环境清单与版本对照搭建前我整理过一份环境清单照着装基本不会出大问题这里直接列出来给所有准备复现的读者参考。组件推荐版本说明JDK1.8建议 8u202 之后的版本RuoYi-Vue 基于 JDK8 编写直接上 JDK17 可能遇到编译兼容问题Maven3.6.x后端依赖管理IDEA 自带版本也可用MySQL5.7 或 8.0数据库8.0 需要额外注意时区配置Redis5.x 以上登录验证码、会话缓存依赖未启动会导致后端启动失败Node.js14.x 或 16.x前端构建环境Vue2 对 Node 高版本兼容性一般IDEIntelliJ IDEA建议手动安装 Lombok 插件并启用注解处理关于 JDK我想多说两句。不要为了求新直接上 JDK17除非你非常清楚框架内部哪些依赖需要怎么适配。我见过不少人用 JDK17 跑若依老项目报了一堆反射相关的错最后老老实实换回 JDK8。另外如果电脑里有多个 JDK 版本IDEA 的 Project Structure 和 Settings 里都要确认选中的是 1.8否则可能会遇到编译期报错但代码看起来没问题的怪象。Redis 是很多第一次接触若依的人会漏掉的一环。RuoYi 的设计里验证码的存取、登录用户信息缓存、Token 的校验都依赖 RedisSpring 容器启动时如果连不上 Redis后端会直接报Unable to connect to Redis并退出。所以正确的启动顺序一定是先把 MySQL 和 Redis 准备好再去启动后端这个顺序后面还会反复强调。2.2 数据库初始化从 SQL 脚本说起拿到 RuoYi 源码之后第一眼应该去看的项目内目录就是sql。这个目录里放着平台运行必须的数据库脚本不同版本内容略有差异常见的是ry_2024xxxx.sql这样的全量脚本外加一个quartz.sql前者包含系统管理相关的所有表结构和基础数据后者是定时任务 Quartz 需要的表。我实际建库的流程是这样的第一步在 MySQL 里创建一个业务数据库不建议直接沿用默认的ry-vue库名。我建的是dikede_db因为后面帝可得的大量业务表也会落到同一个库一个项目一个库的规范从第一天就定下来后面运维和备份都省心。第二步用命令行或者数据库客户端导入全量脚本如果你用的是 MySQL 8导入前确认一下字符集脚本本身通常指定了utf8mb4导入完成后也建议手动确认库和表的字符集确实是utf8mb4否则后面存中文数据乱码会很闹心。第三步导入quartz.sql这个脚本是幂等的重复执行是安全的所以不用担心顺序问题。mysql -uroot -p -e CREATE DATABASE IF NOT EXISTS dikede_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -uroot -p dikede_db ruoyi/sql/ry_2024xxxx.sql mysql -uroot -p dikede_db ruoyi/sql/quartz.sql提示脚本执行完之后别急着关数据库客户端花两分钟浏览一下sys_user、sys_role、sys_menu、sys_user_role这几张核心表的结构。后面代码生成、权限分配、角色配置全部会跟这些表反复打交道提前熟悉能省下很多翻文档的时间。2.3 前端依赖与 Node 环境注意事项前端是标准 Vue 工程安装依赖用npm install就行但在团队协作场景下我每次都会强调三件事。第一package-lock.json文件必须保留并且尽量让所有成员用同一个 Node 大版本。这个文件锁定了依赖树的具体版本保证任何人安装出来的node_modules是一致的。否则有人用 Node14、有人用 Node18依赖树一变化就会出现代码一模一样但有人跑得起来有人跑不起来的诡异现象排查起来极其痛苦。第二耐心等待安装完成不要以为卡住了就反复 CtrlC。npm install在下载原生二进制包时终端可能长时间没有输出尤其是项目里带有node-sass这类需要拉二进制文件的依赖时。如果等了很久最终报编译错误或者提示找不到 Python大概率是网络或 Node 版本兼容问题。最省事的做法是先切到国内镜像源然后清理重装npm config set registry https://registry.npmmirror.com rm -rf node_modules npm install第三依赖装完之后不要急着开前端先把后端和 Redis 准备好。前后端联调最忌讳的就是两端同时出问题到时候前端报错、后端也报错排查半径一下子翻倍。规范的做法是先把后端独立验证通畅再启动前端去做联调每一步都有明确的验证边界。3. 项目导入与核心配置解析3.1 后端项目结构速览把 RuoYi-Vue 导入 IDEA 之后第一件事不是急着点运行而是花十分钟把多模块工程结构认清楚。后端是一个 Maven 多模块工程几个核心模块职责如下ruoyi-admin启动入口模块启动类RuoYiApplication就在这里Controller 大多也放这层ruoyi-framework框架核心Spring Security 配置、拦截器、权限注解、AOP 切面都在这里ruoyi-system系统管理业务用户、角色、菜单、部门、字典这些平台能力的实现ruoyi-quartz定时任务模块封装了 Quartz 调度的相关逻辑ruoyi-generator代码生成器模块提供数据库表到业务代码的自动生成能力ruoyi-common通用工具包常量、基础封装类、工具方法初次接触这类工程的人容易犯一个认知错误看到ruoyi-admin名字里带 admin以为是后台管理页面工程直接忽略。实际上所有后端代码的运行入口就是ruoyi-admin模块你要运行也是运行这个模块。理解了模块职责后面做二次开发才知道新业务代码放在哪不会一股脑往ruoyi-system里塞。顺带说一句ruoyi-system承载的是平台本身的系统管理逻辑混入业务代码会污染模块边界这一点在后面的定制章节还会展开。等 Maven 把依赖下载完IDEA 的 Maven 面板里会列出所有模块。如果某个模块出现红色或者识别不到先在 Maven 面板执行一次Reload All Maven Projects这能解决九成以上的模块导入问题。如果还有依赖找不到检查一下 Maven 的 settings.xml 是否配置了对的镜像源。3.2 application.yml 三个必改配置后端配置主要集中在ruoyi-admin模块的resources目录下需要动的主要是三个位置几乎每个搭建项目都会碰到。第一个是数据源写在application-druid.yml里。默认连接串是jdbc:mysql://localhost:3306/ry-vue要改成你自己的库名dikede_db同时认认真真把时区参数写全MySQL 8 必须设置serverTimezoneAsia/Shanghai否则启动阶段会直接报时区错误。下面是需要修改的核心片段spring: datasource: druid: master: url: jdbc:mysql://localhost:3306/dikede_db?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLtrueserverTimezoneAsia/Shanghai username: root password: your_password第二个是 Redis 连接配置在application.yml里搜redis关键字。默认连本机 6379 端口如果本机 Redis 设置了密码务必补上password字段否则启动时后台一直报认证失败很多人会被这个错误绕进去。第三个是端口和上下文路径server.port默认 8080如果端口被占用改成8090之类的冷门端口即可但改完记住前端代理的 target 地址也要同步改这个联动关系特别容易漏。另外有一个容易被忽略的点是日志路径。RuoYi 默认往../logs目录写日志如果你的启动目录没有写权限应用可能跑一段时间后异常退出报错还不明显。提前在logback.xml里把日志路径改到你有权限的目录能省掉后面大量排查时间。3.3 前端运行与接口代理配置前端工程打开后两个文件必看根目录下的vue.config.js和.env.development。vue.config.js里配置了开发服务器的端口和代理规则。RuoYi-Vue 默认把以/dev-api开头的请求转发到http://localhost:8080也就是说你在浏览器里看到前端请求路径是/dev-api/login实际到达后端的请求路径是/login这是开发环境的代理约定。如果你改了后端端口这里的 target 必须跟着改这个联动关系非常重要。.env.development里定义了VUE_APP_BASE_API默认值就是/dev-apiaxios 请求会自动拼接这个前缀。新手经常在 Network 面板里看到所有请求都有个/dev-api前缀以为是 bug实际上这是设计如此不算错误千万别试图把它去掉。// vue.config.js 关键片段 devServer: { host: 0.0.0.0, port: 80, proxy: { [process.env.VUE_APP_BASE_API]: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { [^ process.env.VUE_APP_BASE_API]: } } } }启动前端用npm run dev成功后终端会打印一个访问地址一般是http://localhost:80或者http://localhost:1024具体以你的配置为准。打开地址看到登录页说明前后端基础设施已经打通了可以进入下一步验证环节。4. 启动验证与首个业务需求落地4.1 启动顺序与验证清单项目能跑通只是第一层目标真正有价值的是用正确顺序启动并且有条理地验证每一个环节。我习惯的启动顺序是MySQL → Redis → 后端 → 前端。这里面有依赖关系后端依赖数据库和 Redis前端依赖后端接口顺序反了排查效率会低很多。后端启动成功的标志不是控制台没报错而是看到类似Started RuoYiApplication in xx seconds的日志输出。如果在这之前看到APPLICATION FAILED TO START不要从头逐行读日志直接定位到Caused by那一行九成是端口占用、数据库连不上、Redis 连不上这三类问题。定位到原因之后修复再重启一次通常都能起起来。启动成功后我会做四个验证确认链路是健康的浏览器直接访问http://localhost:8080能看到一段 JSON 而不是 404说明后端接口层活着用默认账号 admin/admin123 登录系统能正常进入首页说明认证链路 OK随机点几个菜单比如用户管理、角色管理列表数据能加载出来说明权限和数据库查询 OK退出登录后再重新登录一次确认 Token 刷新逻辑没问题提示默认管理员账号密码是平台自带的公共口令项目一旦跑通第一时间去系统管理 → 用户里把密码改掉并到系统配置里打开验证码开关。这类平台的默认口令基本都是公开的不处理等于把大门钥匙挂在门口这个习惯必须养成。4.2 用代码生成器落地第一个模块骨架跑通之后我强烈建议立刻用代码生成器做一个最简单的模块比如积分商品分类把这套流程完整走一遍。这一步的价值不只是产出代码更重要的是让你理解 RuoYi 的业务代码范式Controller 怎么写、Service 怎么分层、Mapper 怎么映射、前端页面怎么组织。后面手写业务模块时能照着这套范式保持风格统一。先建一张规范的业务表例如CREATE TABLE dikede_points_category ( id bigint NOT NULL AUTO_INCREMENT COMMENT 分类ID, category_name varchar(100) NOT NULL COMMENT 分类名称, sort_order int DEFAULT 0 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 (id) ) ENGINEInnoDB COMMENT积分商品分类;然后在系统工具菜单下打开代码生成页面点上方的导入选中刚才建的表。编辑生成配置时包名填com.dikede模块名填points业务名填category功能名写积分商品分类。生成方式选前后端代码确认后生成器会打包一个 ZIP 下载到本地。解压后你会看到三部分内容后端 controller/service/domain/mapper 四层文件前端views/points/category目录下的列表页和表单页以及api目录下的接口定义文件。把文件按目录结构放到对应位置重启后端然后在菜单管理里新增菜单并绑定生成的页面路由和权限标识刷新页面就能对这个分类表做增删改查了。整个过程熟练之后半小时内能完成这也是为什么我坚持用 RuoYi 做基座的核心原因之一。4.3 目录与命名的二次开发约定随着模块越来越多代码组织方式的规范性就变得越来越重要。帝可得的二次开发我在第一天就立了几条约定。第一业务代码不往ruoyi-system里写。理由前面提过ruoyi-system是平台自身的系统管理逻辑混入积分、商品、订单这些业务代码后模块边界会变得模糊未来升级框架或者排查问题时很难分清哪些是平台能力、哪些是业务代码。更优雅的做法是新建一个 Maven 子模块比如dikede-biz专门承载业务域依赖ruoyi-common和ruoyi-system对外提供的能力。第二数据库表和前端目录统一命名规则。表名统一用dikede_前缀前端页面目录按业务域建文件夹例如views/points、views/member、views/goods接口定义文件也对应到api/points、api/member。命名统一是后期维护最大的友好项没有之一。第三业务模块的 Controller 统一继承 RuoYi 封装的BaseController返回结构统一用AjaxResult分页查询统一返回TableDataInfo。直接返回裸对象会在前端解析时报错这些规范在生成器生成的代码里都能看到。遵守平台既有的约定而不是另起炉灶是二次开发成本最低的做法。5. 搭建阶段常见问题排查实录5.1 后端启动失败的高频原因搭建阶段出现问题非常正常我把最高频的几个问题整理成了一个速查表对照着排查效率会高很多。报错关键字根本原因处理方式APPLICATION FAILED TO START Port 8080端口被占用找到占用进程杀掉或修改server.portAccess denied for user数据库账号密码或权限错误核对application-druid.yml确认账号有对应库的权限Unable to connect to RedisRedis 未启动或密码不一致启动 Redis配置文件补password字段Invalid bound statementMapper XML 没有被扫描到检查 MyBatis 的 mapper-locations 配置确认 XML 在 resources 目录下Error creating bean with name某个 Bean 依赖缺失看 Caused by通常是依赖没配全或缓存了旧的 Class 文件这里有一个特别容易忽略的坑IDEA 里停了进程但旧进程其实没有完全退出端口还被占着你启动新进程就一直报端口被占用。解法是先到任务管理器确认没有残留的 Java 进程再重新点击启动而不是反复改端口绕弯子。这个问题在我带过的项目里出现过不止一次每次都浪费了不少时间。还有一个细节如果你改过数据源配置但启动时还是会连到旧的数据库检查一下application-druid.yml是否被 IDEA 识别为配置源文件。IDEA 有时会把 yml 文件标记为普通文本而不参与 Spring 配置加载表现为改配置不生效非常迷惑。选中配置文件右键把它标记为 Spring 配置即可。5.2 前端白屏与接口 404 排查前端页面打开后白屏或者接口一直 404是搭建阶段的高频问题。我遇到这类问题的排查顺序是固定的这里分享给读者参考。第一步先打开浏览器开发者工具的 Network 面板看请求都发到哪去了。如果所有请求都停在/dev-api/...且返回 404先手动在浏览器访问代理目标也就是http://localhost:8080/...如果能正常返回 JSON就说明后端没问题问题出在前端的代理配置回到vue.config.js检查 target 和后端端口是否一致。如果请求压根没有发出去则多半是登录态问题清掉浏览器缓存重新登录一次。第二步如果是白屏但没有任何报错大概率是前端路由动态生成失败。RuoYi 的前端路由是根据当前用户拥有的菜单权限动态生成的如果当前账号没有配置任何菜单登录进去就是一个空壳页面。默认的 admin 账号不会有这个问题自定义账号出现白屏就先去角色管理里把菜单权限勾上再重新登录。还有一类问题是开发服务器实际端口和预期不一致。Vue 开发服务器在端口被占用时可能自动换端口终端有提示但你没注意就关掉了再打开浏览器时用的还是旧端口地址。遇到页面打不开先看终端输出的实际地址用那个地址访问不要坚持记忆里的端口。5.3 个人踩坑记录与习惯建议分享几个我在这类项目搭建中真正被坑过的地方希望能帮后来者少走一些弯路。第一依赖版本不能随便升。有次为了图新把 Maven 仓库里的 Spring Boot 从 2.5 升到 2.7结果框架里某个过时的 API 直接编译报错整个团队等我排查折腾了半下午。这类快速开发平台的版本组合是经过官方测试的升级任何一环都要做整体评估而不是只盯一个包。第二代码生成器的 SQL 脚本一定要自己审核一遍。生成器能识别大部分字段但如果你在建表 SQL 里写了奇怪的类型或者不规范的注释生成器产出的代码也会有瑕疵。至少要看一眼生成的 Domain 字段类型和数据库里面是不是对得上不要无脑把生成结果直接丢进项目。第三从项目第一天就维护一个 README 和上线 Checklist。这份文档不用写得多花哨把手头实际需要的操作步骤写清楚就行启动前要开 Redis、数据库脚本执行到哪个文件、前端代理指向哪个端口、默认账号密码是什么。团队里任何一个新人照着跑就能把环境搭起来这一点看起来跟写代码无关但对团队整体效率的提升是立竿见影的。第四尽量统一开发环境配置。团队里有人用 Mac、有人用 Windows、有人用 Linux文件路径和大小写敏感问题都会冒出来。至少把 MySQL 的时区、Redis 的空密码、Node 版本统一约定团队内部约定一个标准环境文档能砍掉一半的环境类事故。我在实际项目里的做法是把这份文档和项目代码放在同一个仓库里维护每次有人加入第一件事就是照文档搭环境基本没有因为环境问题额外花过时间。