# 聚合启动器（rui-service-starter）使用文档 ## 1. 什么是聚合启动器 `rui-service-starter` 是将多个业务微服务合并为一个 Spring Boot 应用启动的**轻量化部署方案**。 | 模块 | 说明 | |------|------| | `rui-service-system` | 系统管理服务（菜单、角色、部门、字典、租户等） | | `rui-service-user` | 用户基础服务（用户、等级、权限等） | > **认证中心（rui-auth）和网关（rui-gateway）保持独立**，不参与聚合。 --- ## 2. 适用场景 | 场景 | 推荐模式 | |------|---------| | 中小型项目、团队规模 < 10 人 | ✅ **聚合模式**（节省资源、简化部署） | | 大型项目、多团队并行开发 | 独立微服务模式（服务隔离、独立发布） | | 从单体向微服务过渡 | ✅ **聚合模式**（先聚合后拆分） | | 本地开发调试 | ✅ **聚合模式**（一键启动所有业务） | **聚合模式优势：** - 减少 JVM 内存占用（节省 500MB+） - 减少 Nacos 注册中心压力 - 一次打包、一次部署、一次启动 - 本地开发只需启动 3 个服务（gateway + auth + starter） --- ## 3. 架构说明 ### 3.1 独立微服务模式（默认） ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ Gateway │────▶│ rui-auth │────▶│ rui-service-xxx │ │ :9300 │ │ :9301 │ │ :9302~930N │ └─────────────┘ └─────────────┘ └─────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ rui-service-system rui-service-user :9302 :9303 ``` ### 3.2 聚合模式 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ Gateway │────▶│ rui-auth │────▶│ rui-service-starter │ │ :9300 │ │ :9301 │ │ :9399 │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ [system 模块] [user 模块] 共享 JVM + 端口 ``` --- ## 4. 快速启动 ### 4.1 编译 ```bash cd backend # 编译聚合启动器（自动编译依赖模块） mvn clean install -pl rui-service/rui-service-starter -am -DskipTests ``` ### 4.2 本地开发启动 ```bash # 方式一：IDE 直接运行 StarterApplication.java # 方式二：命令行启动 java -jar rui-service/rui-service-starter/target/rui-service-starter-1.0.0-SNAPSHOT.jar ``` ### 4.3 生产环境启动 ```bash # 指定环境变量（也可在 Nacos 中配置） java -jar rui-service-starter-1.0.0-SNAPSHOT.jar \ --NACOS_SERVER_ADDR=127.0.0.1:8848 \ --spring.profiles.active=prod ``` --- ## 5. 端口与服务名 | 服务 | 端口 | Nacos 服务名 | 说明 | |------|------|-------------|------| | rui-gateway | 9300 | rui-gateway | 网关（保持独立） | | rui-auth | 9301 | rui-auth | 认证中心（保持独立） | | rui-service-system | 9302 | rui-service-system | 系统服务（独立模式） | | rui-service-user | 9303 | rui-service-user | 用户服务（独立模式） | | **rui-service-starter** | **9399** | **rui-service-starter** | **聚合启动器（替代 system + user）** | --- ## 6. 网关路由配置 Nacos `rui-gateway.yaml` 中已默认使用聚合模式，将 `/system/**` 和 `/user/**` 统一路由到 `rui-service-starter`： ```yaml spring: cloud: gateway: server: webflux: routes: - id: rui-auth uri: lb://rui-auth predicates: - Path=/auth/** filters: - StripPrefix=0 # ========== 聚合模式（默认，中小型项目）========== - id: rui-service-starter uri: lb://rui-service-starter predicates: - Path=/user/**,/system/** filters: - StripPrefix=0 # ========== 独立微服务模式（大型项目）========== # - id: rui-service-user # uri: lb://rui-service-user # predicates: # - Path=/user/** # filters: # - StripPrefix=0 # - id: rui-service-system # uri: lb://rui-service-system # predicates: # - Path=/system/** # filters: # - StripPrefix=0 ``` > **提示**：如需切换到独立模式，取消注释独立路由并注释掉聚合路由即可。 --- ## 7. Feign 调用说明 ### 7.1 聚合模式下的 Feign 行为 | Feign 接口 | 目标服务 | 默认指向 | 说明 | |-----------|---------|---------|------| | `UserAuthFeign` | `rui-service-user` | `rui-service-starter` | 通过 Nacos 路由到聚合启动器 | | `SystemClientFeign` | `rui-service-system` | `rui-service-starter` | 通过 Nacos 路由到聚合启动器 | | `TokenManageFeign` | `rui-auth` | `rui-auth` | 认证中心保持独立 | ### 7.2 配置原理 FeignClient 的 `value` 属性使用 `${feign.providers.xxx}` 变量，默认指向聚合启动器： ```java @FeignClient(contextId = "userAuthFeign", value = "${feign.providers.user:rui-service-starter}", // 默认指向聚合启动器 path = "/user/inner") ``` **Nacos `rui-common.yaml` 中的公共配置：** ```yaml feign: providers: user: rui-service-starter # 用户服务：默认指向聚合启动器 system: rui-service-starter # 系统服务：默认指向聚合启动器 auth: rui-auth # 认证中心：保持独立 ``` **切换独立模式**：在对应服务的 Nacos 配置中覆盖： ```yaml feign: providers: user: rui-service-user # 改回独立用户服务 system: rui-service-system # 改回独立系统服务 ``` --- ## 8. Nacos 配置建议 ### 8.1 配置中心 聚合启动器启动时会加载以下 Nacos 配置： | 配置文件 | 说明 | |---------|------| | `rui-service-starter.yaml` | 聚合服务专属配置（可选） | | `rui-common.yaml` | 公共配置（日志、线程池等） | | `rui-data.yaml` | 数据源配置（MySQL、Redis 等） | ### 8.2 配置继承 聚合模式下，`rui-service-starter.yaml` 可以覆盖 `rui-service-system.yaml` 和 `rui-service-user.yaml` 中的冲突配置。 建议将**业务无关的基础配置**放到 `rui-common.yaml`，**数据库连接等环境配置**放到 `rui-data.yaml`。 --- ## 9. 两种模式切换指南 ### 9.1 从独立模式切换到聚合模式 1. **停止** `rui-service-user` 和 `rui-service-system` 2. **启动** `rui-service-starter` 3. **修改网关路由**（见 6.1） 4. **完成** ### 9.2 从聚合模式切换到独立模式 1. **停止** `rui-service-starter` 2. **启动** `rui-service-system`（端口 9302）和 `rui-service-user`（端口 9303） 3. **修改网关路由**（见 6.2） 4. **完成** ### 9.3 代码层面注意事项 - 聚合模式下，**所有业务代码无需修改** - 两个服务的 `@RestController` 路由前缀不同（`/system/**` 和 `/user/**`），天然无冲突 - Mapper 扫描范围 `com.rui.**.mapper` 已覆盖两个模块 --- ## 10. 常见问题 ### Q1: 聚合启动器内存占用多少？ > 约 400~600MB（JVM Heap），比同时启动 user + system（约 800MB+）节省 30%~50%。 ### Q2: 可以再加其他服务吗？ > 可以。在 `rui-service-starter/pom.xml` 中增加依赖即可： > ```xml > > com.rui > rui-service-order > ${revision} > > ``` > 同时确保新服务的 Controller 路由前缀不与现有服务冲突。 ### Q3: 聚合模式下事务跨服务吗？ > 同一 JVM 内，system 和 user 的 Service 互相调用时，**Spring 本地事务仍然有效**。但建议保持服务边界清晰，避免过度耦合。 ### Q4: 日志怎么区分是哪个模块的？ > 日志文件统一输出到 `logs/rui-service-starter/`，通过日志内容中的类名（`com.rui.service.system.xxx` / `com.rui.service.user.xxx`）区分来源模块。 ### Q5: 健康检查端点是什么？ > `GET http://localhost:9399/actuator/health` ### Q6: 聚合模式和独立模式可以同时运行吗？ > **不建议**。会导致 Nacos 中同时存在 `rui-service-starter` 和 `rui-service-user/system`，Feign 调用可能出现负载均衡到错误实例的情况。 --- ## 11. 本地开发推荐启动顺序 聚合模式下，本地开发只需启动 3 个服务： ```bash # 1. 启动 Nacos（如果本地运行） sh startup.sh -m standalone # 2. 启动 Redis（如果本地运行） redis-server # 3. 启动 MySQL（如果本地运行） # 4. 启动 rui-auth（认证中心） java -jar rui-auth/target/rui-auth-*.jar # 5. 启动 rui-gateway（网关） java -jar rui-gateway/target/rui-gateway-*.jar # 6. 启动 rui-service-starter（聚合业务服务） java -jar rui-service/rui-service-starter/target/rui-service-starter-*.jar ``` > 相比独立模式（需要启动 5+ 个服务），开发效率大幅提升。 --- ## 12. 文档更新记录 | 日期 | 版本 | 说明 | |------|------|------| | 2026-05-30 | 1.0 | 初始版本，聚合 system + user |