docs(ai-skills): 添加 Nacos 配置与 application.yml 规范文档

- 明确 5 条配置规则 - 提供正确/错误示例 - 说明配置分层和同步流程
2026-06-05 10:20:12 +08:00
parent 2277bca1ad
commit ee335fe90a
1 changed files with 267 additions and 0 deletions
@@ -0,0 +1,267 @@
+# 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/本地配置的一致性和可维护性，请务必遵守！