若依微服务实战：从零构建Nacos版Ruoyi-Cloud前后端分离项目
1. 环境准备：避开那些新手必踩的坑
第一次接触Ruoyi-Cloud+Nacos组合时，我像大多数开发者一样直接照着官方文档操作，结果在环境配置阶段就卡了整整两天。现在回想起来，很多问题其实都有预警信号，只是当时没经验。先说几个容易忽略的致命细节：
JDK版本看似简单却最容易出问题。我遇到过明明装了JDK1.8却启动失败的情况，后来发现是系统同时存在多个JDK版本导致环境变量冲突。建议用java -version和javac -version双重验证，确保版本一致。如果使用Docker部署Nacos，记得宿主机和容器内的JDK版本也要匹配。
MySQL5.7的sql_mode配置是个隐藏杀手。Ruoyi-Cloud的SQL脚本包含GROUP BY语句，如果MySQL启用了ONLY_FULL_GROUP_BY模式会导致执行失败。建议在my.cnf中加入：
[mysqld] sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTIONNacos的端口冲突问题经常被低估。有次启动服务始终注册不上Nacos，后来发现是忘了Nacos2.0新增的9848/9849端口没开放。完整端口清单如下：
- 8848：主服务端口（必须开放）
- 9848：客户端gRPC请求端口（Java应用通信用）
- 9849：服务端gRPC请求端口（集群通信用）
Redis安装建议用Docker一步到位：
docker run --name redis -p 6379:6379 -d redis:6-alpine --requirepass "yourpassword"但要注意，如果Redis设了密码，必须在所有微服务的配置文件中同步修改，包括ry-config数据库里的content字段。
2. 系统运行：从启动到登录的完整闭环
2.1 后端模块启动的隐藏逻辑
官方文档说模块启动没有顺序要求，但实际测试中发现网关必须最先启动，否则其他服务注册时会报"找不到路由"错误。正确的启动顺序应该是：
- RuoYiGatewayApplication（网关）
- RuoYiAuthApplication（认证）
- 其他业务模块
有个特别容易中招的点：Nacos控制台显示服务已注册，但接口调用返回404。这时候要检查网关模块的application.yml，确保有正确的路由配置：
spring: cloud: gateway: routes: - id: system uri: lb://ruoyi-system predicates: - Path=/system/**2.2 前端那些防不胜防的坑
第一次运行前端时，我遇到了npm install卡死的问题。后来发现用淘宝镜像也要注意版本：
# 推荐组合 npm config set registry https://registry.npmmirror.com npm install --legacy-peer-deps--legacy-peer-deps参数能解决依赖冲突问题，这在React17+的版本中特别常见。
登录页面白屏？八成是.env.development文件配置不对：
# 必须与后端网关端口一致 VUE_APP_BASE_API = 'http://localhost:8080'如果用了Nginx反向代理，记得处理跨域：
location /prod-api/ { proxy_pass http://gateway:8080/; proxy_set_header Host $host; }3. 新增微服务模块实战
3.1 从零创建jxbd模块
新建模块绝不是简单的复制粘贴。我以ruoyi-system为模板创建ruoyi-jxbd时，踩过三个深坑：
坑一：pom.xml的依赖地狱
<!-- 必须包含这两个核心依赖 --> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> </dependency> <dependency> <groupId>com.ruoyi</groupId> <artifactId>ruoyi-common-core</artifactId> </dependency>缺少前者会导致服务无法注册，缺少后者会引发SpringBean注入失败。
坑二：bootstrap.yml的魔鬼细节
spring: application: name: ruoyi-jxbd # 必须与Nacos配置中心的data_id前缀一致 cloud: nacos: config: file-extension: yml # 必须与Nacos中配置的格式相同 shared-configs[0]: application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}坑三：Nacos配置的死亡陷阱在ry-config库执行INSERT时，content字段的YAML格式必须严格遵循缩进规则。建议先用在线YAML校验工具检查，特别是包含特殊字符的值要用引号包裹：
INSERT INTO `ry-config`.config_info (data_id, group_id, content) VALUES ( 'ruoyi-jxbd-dev.yml', 'DEFAULT_GROUP', 'spring: redis: host: "192.168.1.100" # 字符串建议加引号 port: 6379' );3.2 接口开发的黄金法则
新建Controller时，我总结出三条铁律：
- 所有API必须继承
BaseController - 方法首参必须是
HttpServletRequest - 返回结果统一用
AjaxResult
典型示例：
@RestController @RequestMapping("/jxbd/demo") public class JxbdDemoController extends BaseController { @GetMapping("/list") public AjaxResult list(HttpServletRequest request) { startPage(); // 自动处理分页参数 List<Demo> list = demoService.selectDemoList(); return success(getDataTable(list)); } }Swagger集成也有讲究，要在模块的resources目录下放springfox.documentation.swagger2.mappers文件，否则接口文档会报类型转换错误。
4. 调试与排错终极指南
4.1 日志分析的三个关键点
- 网关日志要看
GatewayFilter链：
DEBUG 8888 --- [ctor-http-nio-3] o.s.c.g.f.OrderedGatewayFilterFactory : Filter processed in 12ms- Nacos日志要关注心跳：
INFO [com.alibaba.nacos.client.naming] Report instance current ips: 2- 数据库连接要监控连接池：
DEBUG [com.alibaba.druid.pool.DruidDataSource] getConnection direct retry : 14.2 常见错误速查表
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| 服务注册失败 | 端口冲突/网络隔离 | 检查8848,9848,9849端口 |
| 接口返回404 | 网关路由缺失 | 更新gateway的路由配置 |
| 登录后跳转循环 | Redis连接失败 | 检查密码和防火墙设置 |
| 页面加载慢 | 前端代理错误 | 确认VUE_APP_BASE_API值 |
4.3 性能调优实战
压测时发现QPS上不去？试试这些参数优化：
# gateway优化 spring: cloud: gateway: httpclient: pool: max-idle-time: 60000 max-connections: 1000 # tomcat优化 server: tomcat: max-threads: 800 min-spare-threads: 100数据库连接池建议配置：
druid: initial-size: 10 max-active: 100 validation-query: SELECT 1 test-while-idle: true time-between-eviction-runs-millis: 60000最后说个血泪教训：永远不要在生产环境直接用npm run dev启动前端，应该用：
npm run build:prod && nginx -g 'daemon off;'