268 lines
6.9 KiB
Markdown
268 lines
6.9 KiB
Markdown
# RUI 项目 Nacos 配置与 application.yml 规范
|
||
|
||
> **适用范围**: rui-framework 后端框架所有模块
|
||
> **更新日期**: 2026-06-05
|
||
> **强制级别**: 必须遵守，AI 编辑相关文件时自动强制执行
|
||
|
||
---
|
||
|
||
## 核心原则
|
||
|
||
### 1. 配置分层
|
||
|
||
| 配置位置 | 用途 | 内容 |
|
||
|---------|------|------|
|
||
| **Nacos** (`docs/backend/config-templates/nacos/*.yaml`) | 动态配置 | 端口、业务配置 |
|
||
| **本地** (`src/main/resources/application.yml`) | 兜底配置 | 基础框架配置 + Nacos 连接信息 |
|
||
| **公共** (`rui-common.yaml`, `rui-data.yaml`) | 共享配置 | Feign、Redis、数据库等 |
|
||
|
||
### 2. 禁止重复
|
||
|
||
**Nacos 服务专属配置只放：端口 + 该服务特有的业务配置**
|
||
|
||
- ❌ **禁止**：在 `rui-service-*.yaml` 中放 nacos/feign/redis/数据库配置
|
||
- ✅ **正确**：只放 `server.port` 和业务配置（如 `rui.modules`）
|
||
|
||
### 3. 单向同步
|
||
|
||
**Nacos 配置为准，`src/main/resources/application.yml` 必须和 Nacos 配置完全一致。**
|
||
|
||
修改流程：
|
||
1. 先修改 `docs/backend/config-templates/nacos/*.yaml`（Nacos 源文件）
|
||
2. 推送到 Nacos
|
||
3. 复制内容到 `src/main/resources/application.yml`（本地兜底）
|
||
|
||
> ⚠️ **禁止**：两个文件内容不一致
|
||
|
||
### 4. 推送必验证
|
||
|
||
推送 Nacos 后必须验证：
|
||
|
||
```bash
|
||
curl "http://192.168.31.210:8848/nacos/v1/cs/configs?dataId=xxx.yaml&group=DEFAULT_GROUP&tenant=rui-dev&username=nacos&password=nacos"
|
||
```
|
||
|
||
---
|
||
|
||
## 规则详解
|
||
|
||
### Rule 1：application.yml 严格模板化
|
||
|
||
**要求**：
|
||
|
||
- 新建模块或 `application.yml` 丢失时，**完整复制** `docs/backend/config-templates/application-template.yml`
|
||
- **禁止合并**其他内容
|
||
- **禁止新增**任何模板外的内容
|
||
- 只允许修改模板中**明确标注允许修改**的位置
|
||
|
||
**当前模板中允许修改的位置**：
|
||
|
||
1. `server.port` — 按模块端口规划填写
|
||
2. 无 MyBatis 的模块删除 `rui-data` 的 `config.import`
|
||
|
||
> 未来如果 `application-template.yml` 更新并新增可修改项，以模板中的注释标注为准。
|
||
|
||
### Rule 2：业务配置全进 Nacos
|
||
|
||
**要求**：
|
||
|
||
- 各模块特有业务配置必须写在 `docs/backend/config-templates/nacos/{模块名称}.yaml`
|
||
- 例：`rui-service-system` → `rui-service-system.yaml`
|
||
- 例：`rui-gateway` → `rui-gateway.yaml`
|
||
- 例：`rui-auth` → `rui-auth.yaml`
|
||
- 修改完成后必须推送到 Nacos
|
||
- Nacos 服务配置**不得包含** `application.yml` 中的通用内容，包括但不限于：
|
||
- Nacos 连接配置（`spring.cloud.nacos.discovery/config`）
|
||
- Spring 生命周期（`spring.lifecycle`）
|
||
- 自动配置排除（`spring.autoconfigure.exclude`）
|
||
- 文件上传限制（`spring.servlet.multipart`）
|
||
- 编码配置（`spring.servlet.encoding`）
|
||
- OpenFeign 断路器（`spring.cloud.openfeign.circuitbreaker`）
|
||
- `management.endpoints`
|
||
- `logging.file.path`
|
||
|
||
**例外**：如果某模块确实需要覆盖 application.yml 中的某个默认值，可以在 Nacos 配置中显式覆盖，但必须在注释中说明理由。
|
||
|
||
### Rule 3：公共配置职责分离
|
||
|
||
**要求**：
|
||
|
||
| 配置文件 | 职责范围 | 典型内容 |
|
||
|---------|---------|---------|
|
||
| `rui-common.yaml` | 所有模块都可能用到的通用配置 | Redis、RabbitMQ、Jackson、JWT、安全白名单、Feign providers |
|
||
| `rui-data.yaml` | 仅数据库相关模块导入 | 数据源、MyBatis Plus、Seata |
|
||
|
||
**原因**：没有使用数据库的模块（如 Gateway）也可能需要 Redis，因此 Redis 不能放在 `rui-data.yaml`。
|
||
|
||
### Rule 4：推送必验证
|
||
|
||
**要求**：
|
||
|
||
修改 Nacos 配置并推送后，必须执行验证命令：
|
||
|
||
```bash
|
||
curl "http://192.168.31.210:8848/nacos/v1/cs/configs?dataId={dataId}.yaml&group=DEFAULT_GROUP&tenant=rui-dev&username=nacos&password=nacos"
|
||
```
|
||
|
||
### Rule 5：本地开发配置不干预
|
||
|
||
**要求**：
|
||
|
||
- `config/application-dev.yml` 属于本地开发配置
|
||
- 可由开发人员填写完整配置或仅本地特性配置
|
||
- AI 正常情况下**不修改**该文件
|
||
|
||
---
|
||
|
||
## 正反对照示例
|
||
|
||
### 示例 1：application.yml
|
||
|
||
**正确**（仅修改允许位置）：
|
||
|
||
```yaml
|
||
server:
|
||
port: 9302 # ✅ 【允许修改】按模块规划填写
|
||
shutdown: graceful
|
||
# ... 其余与模板完全一致 ...
|
||
```
|
||
|
||
**错误**：
|
||
|
||
```yaml
|
||
server:
|
||
port: 9302
|
||
|
||
# ❌ 错误：在 application.yml 中添加业务配置
|
||
rui:
|
||
modules:
|
||
available:
|
||
- code: demo
|
||
name: 演示中心
|
||
```
|
||
|
||
### 示例 2：Nacos 服务配置
|
||
|
||
**正确**（仅端口 + 业务配置）：
|
||
|
||
```yaml
|
||
# rui-service-pay.yaml
|
||
server:
|
||
port: 9307
|
||
|
||
payment:
|
||
order-timeout: 30
|
||
notify-max-times: 5
|
||
```
|
||
|
||
**错误**：
|
||
|
||
```yaml
|
||
# rui-service-xxx.yaml
|
||
server:
|
||
port: 9307
|
||
|
||
# ❌ 错误：Nacos 配置中重复 application.yml 内容
|
||
spring:
|
||
cloud:
|
||
nacos:
|
||
discovery:
|
||
server-addr: ${NACOS_SERVER_ADDR:nacos:8848}
|
||
lifecycle:
|
||
timeout-per-shutdown-phase: 30s
|
||
```
|
||
|
||
### 示例 3：公共配置职责
|
||
|
||
**正确**：
|
||
|
||
```yaml
|
||
# rui-common.yaml
|
||
spring:
|
||
data:
|
||
redis:
|
||
host: ${REDIS_HOST:192.168.31.210}
|
||
```
|
||
|
||
```yaml
|
||
# rui-data.yaml
|
||
spring:
|
||
datasource:
|
||
url: jdbc:mysql://...
|
||
```
|
||
|
||
**错误**：
|
||
|
||
```yaml
|
||
# rui-data.yaml
|
||
spring:
|
||
data:
|
||
redis:
|
||
host: ...
|
||
# ❌ 错误：Redis 配置不应放在 rui-data.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 修改流程
|
||
|
||
### 修改 Nacos 配置的完整流程
|
||
|
||
1. **编辑 Nacos 源文件**
|
||
```bash
|
||
vim docs/backend/config-templates/nacos/rui-service-xxx.yaml
|
||
```
|
||
|
||
2. **推送到 Nacos**
|
||
- 通过 Nacos 控制台或 API 推送
|
||
|
||
3. **验证推送结果**
|
||
```bash
|
||
curl "http://192.168.31.210:8848/nacos/v1/cs/configs?dataId=rui-service-xxx.yaml&group=DEFAULT_GROUP&tenant=rui-dev&username=nacos&password=nacos"
|
||
```
|
||
|
||
4. **同步到本地 application.yml（如需要）**
|
||
- 仅当本地 application.yml 需要兜底内容时更新
|
||
- 内容必须与 Nacos 保持一致
|
||
|
||
### 新建模块的配置初始化流程
|
||
|
||
1. **复制 application.yml 模板**
|
||
```bash
|
||
cp docs/backend/config-templates/application-template.yml \
|
||
rui-service/rui-service-xxx/src/main/resources/application.yml
|
||
```
|
||
|
||
2. **修改允许修改的位置**
|
||
- `server.port` — 按端口规划填写
|
||
- 无 MyBatis 的模块删除 `rui-data` 导入
|
||
|
||
3. **创建 Nacos 配置文件**
|
||
```bash
|
||
vim docs/backend/config-templates/nacos/rui-service-xxx.yaml
|
||
```
|
||
- 只写 `server.port` + 业务配置
|
||
|
||
4. **推送 Nacos 并验证**
|
||
|
||
---
|
||
|
||
## 检查清单
|
||
|
||
### 编辑前检查
|
||
|
||
- [ ] 本次修改是否涉及 `application.yml` 或 Nacos 配置？
|
||
- [ ] 是否在允许修改的范围内？
|
||
- [ ] 是否将业务配置放在了正确的位置？
|
||
|
||
### 编辑后检查
|
||
|
||
- [ ] `application.yml` 是否仍与模板一致？
|
||
- [ ] Nacos 配置是否未包含 application.yml 中已有的通用配置？
|
||
- [ ] 修改是否已同步到 Nacos 源文件和本地 application.yml（如适用）？
|
||
- [ ] 是否已按 Rule 4 推送后验证？
|
||
|
||
---
|
||
|
||
> **最后提醒**：配置规范是为了保证 Nacos/本地配置的一致性和可维护性，请务必遵守！
|