vifo
19de7e24ec
从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
303 lines
9.9 KiB
Markdown
303 lines
9.9 KiB
Markdown
# 聚合启动器（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
|
||
> <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 个服务：
|
||
|
||
```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 |
|