rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 迁移 spring-ai 通用文档到 rui-docs

Browse Source 
从 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分模块打包设计
This commit is contained in:
pigeon
2026-06-04 09:31:24 +08:00
parent 2e38c53434
commit 19de7e24ec
36 changed files with 5872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/guides/聚合启动器使用文档.md
+302
View File
@@ -0,0 +1,302 @@
# 聚合启动器（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 |