前言若依RuoYi是国内使用最广泛的开源后台管理框架之一基于 Spring Boot 构建开箱即用省去大量重复的基础建设工作。若依有多个版本其中RuoYi-Cloud是微服务版本基于 Spring Cloud Spring Cloud Alibaba 构建适合有一定规模、需要多服务独立部署的项目。本文将帮你理解它的整体架构和核心模块。一、若依微服务版的技术栈层次技术服务注册与发现Nacos配置中心Nacos Config网关Spring Cloud Gateway负载均衡Spring Cloud LoadBalancer远程调用OpenFeign熔断降级Sentinel权限认证Spring Security JWT缓存Redis数据库MySQL MyBatis Plus日志链路追踪SkyWalking可选容器化Docker Docker Compose二、整体架构若依微服务的请求流转过程如下客户端浏览器/App ↓ Gateway 网关统一入口鉴权、路由、限流 ↓ Auth 认证服务登录、Token 签发与验证 ↓ 各业务微服务System、Monitor、Job 等 ↓ MySQL / Redis / Nacos所有外部请求都必须经过网关网关负责路由转发把/system/**的请求转发到 system 服务Token 验证未登录直接拦截限流防止恶意刷接口三、核心模块解析1. ruoyi-gateway网关模块整个系统的统一入口基于 Spring Cloud Gateway 实现。核心配置在bootstrap.yml中定义路由规则spring: cloud: gateway: routes: - id: ruoyi-system uri: lb://ruoyi-system # lb:// 表示负载均衡从 Nacos 发现服务 predicates: - Path/system/** # 匹配路径 filters: - StripPrefix1 # 去掉路径前缀网关还内置了一个Token 过滤器每个请求到来时先验证 JWT Token 是否有效无效则直接返回 401不会让请求打到后端服务。2. ruoyi-auth认证模块负责用户登录和 Token 管理流程如下用户提交账号密码 ↓ Auth 服务校验查 MySQL比对密码 ↓ 生成 JWT Token 用户信息存入 Redis ↓ 返回 Token 给客户端 ↓ 客户端后续请求携带 Token → 网关验证 → 从 Redis 取用户信息Token 存在 Redis 中而不只是依靠 JWT 自验证是为了能主动让 Token 失效比如用户被封号、强制下线。3. ruoyi-system系统模块最核心的业务模块包含用户管理增删改查用户分配角色角色管理定义角色绑定菜单权限菜单管理树形菜单结构控制前端页面可见性部门管理组织架构树字典管理维护系统中的枚举值如性别、状态等操作日志记录谁在什么时间做了什么操作这套 RBAC基于角色的权限控制模型是若依的核心设计用户 → 角色 → 菜单/权限。4. ruoyi-modules业务模块目录这是你自己业务代码的归宿。若依提供了ruoyi-modules目录作为扩展入口你可以在这里新建自己的微服务模块比如ruoyi-modules/ ├── ruoyi-system/ # 框架自带 ├── ruoyi-job/ # 定时任务自带 ├── ruoyi-file/ # 文件服务自带 └── your-business/ # 你自己的业务模块 ← 在这里扩展5. ruoyi-common公共模块存放各个微服务都会用到的公共代码ruoyi-common-core基础工具类、统一返回结果、全局异常处理ruoyi-common-redisRedis 操作封装ruoyi-common-security权限注解、Token 解析工具ruoyi-common-swagger接口文档配置通过 Maven 依赖引入各服务直接复用避免重复造轮子。四、Nacos注册中心 配置中心Nacos 在若依微服务中承担双重职责作为注册中心每个微服务启动时向 Nacos 注册自己的地址其他服务通过 Nacos 发现它实现服务间通信不需要硬编码 IP。作为配置中心把数据库地址、Redis 配置、各种开关等配置统一存在 Nacos修改后不需要重启服务即可生效。# bootstrap.yml 中指定配置中心地址 spring: cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yml discovery: server-addr: 127.0.0.1:8848五、如何新增一个业务模块以新增一个设备管理模块为例步骤如下在ruoyi-modules下新建 Maven 模块ruoyi-device引入公共依赖在pom.xml中引入ruoyi-common-core、ruoyi-common-security等写业务代码Controller、Service、Mapper和普通 Spring Boot 项目一样在 Nacos 中添加配置数据库、Redis 等配置在 Gateway 中添加路由规则将/device/**路由到新服务在 System 模块中添加菜单和权限让前端能看到新模块的入口整个过程的核心是业务代码你来写基础设施若依已经搭好了。六、本地快速启动若依提供了 Docker Compose 文件可以一键启动基础设施# 克隆项目 git clone https://gitee.com/y_project/RuoYi-Cloud.git # 启动基础设施MySQL、Redis、Nacos cd docker docker-compose up -d # 按顺序启动各服务 # 1. 先启动 Gateway 和 Auth # 2. 再启动 System 等业务服务启动顺序很重要必须先有 Nacos注册中心其他服务才能注册上去。七、常见踩坑点问题原因解决服务启动找不到配置Nacos 中没有对应的配置文件在 Nacos 控制台手动创建配置接口返回 401Token 未携带或已过期检查请求头Authorization: Bearer xxx服务间调用失败Feign 接口定义与实际接口不匹配对齐路径、参数类型网关路由不生效路由配置写错或未刷新检查 Gateway 配置必要时重启总结若依微服务版的核心价值在于把微服务架构中最繁琐的基础设施鉴权、网关、注册中心、配置中心、日志都搭好了开发者只需要专注在业务逻辑上。对于中小团队来说直接基于若依二次开发能节省大量时间。代价是需要花时间理解它的架构设计避免在不理解原理的情况下盲目修改导致问题。