rui-docs/backend/guides/聚合启动器使用文档.md

聚合启动器（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 编译

cd backend

# 编译聚合启动器（自动编译依赖模块）
mvn clean install -pl rui-service/rui-service-starter -am -DskipTests

4.2 本地开发启动

# 方式一：IDE 直接运行 StarterApplication.java
# 方式二：命令行启动
java -jar rui-service/rui-service-starter/target/rui-service-starter-1.0.0-SNAPSHOT.jar

4.3 生产环境启动

# 指定环境变量（也可在 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：

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} 变量，默认指向聚合启动器：

@FeignClient(contextId = "userAuthFeign",
             value = "${feign.providers.user:rui-service-starter}",  // 默认指向聚合启动器
             path = "/user/inner")

Nacos rui-common.yaml 中的公共配置：

feign:
  providers:
    user: rui-service-starter      # 用户服务：默认指向聚合启动器
    system: rui-service-starter    # 系统服务：默认指向聚合启动器
    auth: rui-auth                 # 认证中心：保持独立

切换独立模式：在对应服务的 Nacos 配置中覆盖：

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 中增加依赖即可：

<dependency>
    <groupId>com.rui</groupId>
    <artifactId>rui-service-order</artifactId>
    <version>${revision}</version>
</dependency>

同时确保新服务的 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 个服务：

# 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