# 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/本地配置的一致性和可维护性，请务必遵守！