Files

T

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

- 明确 5 条配置规则
- 提供正确/错误示例
- 说明配置分层和同步流程

2026-06-05 10:20:12 +08:00

6.9 KiB

Raw Permalink Blame History

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 配置完全一致。

修改流程：

先修改 docs/backend/config-templates/nacos/*.yaml（Nacos 源文件）
推送到 Nacos
复制内容到 src/main/resources/application.yml（本地兜底）

⚠️ 禁止：两个文件内容不一致

4. 推送必验证

推送 Nacos 后必须验证：

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
禁止合并其他内容
禁止新增任何模板外的内容
只允许修改模板中明确标注允许修改的位置

当前模板中允许修改的位置：

server.port — 按模块端口规划填写
无 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 配置并推送后，必须执行验证命令：

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

正确（仅修改允许位置）：

server:
  port: 9302                 # ✅ 【允许修改】按模块规划填写
  shutdown: graceful
  # ... 其余与模板完全一致 ...

错误：

server:
  port: 9302

# ❌ 错误：在 application.yml 中添加业务配置
rui:
  modules:
    available:
      - code: demo
        name: 演示中心

示例 2：Nacos 服务配置

正确（仅端口 + 业务配置）：

# rui-service-pay.yaml
server:
  port: 9307

payment:
  order-timeout: 30
  notify-max-times: 5

错误：

# 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：公共配置职责

正确：

# rui-common.yaml
spring:
  data:
    redis:
      host: ${REDIS_HOST:192.168.31.210}

# rui-data.yaml
spring:
  datasource:
    url: jdbc:mysql://...

错误：

# rui-data.yaml
spring:
  data:
    redis:
      host: ...
  # ❌ 错误：Redis 配置不应放在 rui-data.yaml

修改流程

修改 Nacos 配置的完整流程

编辑 Nacos 源文件

vim docs/backend/config-templates/nacos/rui-service-xxx.yaml

推送到 Nacos
- 通过 Nacos 控制台或 API 推送

验证推送结果

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"

同步到本地 application.yml（如需要）
- 仅当本地 application.yml 需要兜底内容时更新
- 内容必须与 Nacos 保持一致

新建模块的配置初始化流程

复制 application.yml 模板

cp docs/backend/config-templates/application-template.yml \
   rui-service/rui-service-xxx/src/main/resources/application.yml

修改允许修改的位置
- server.port — 按端口规划填写
- 无 MyBatis 的模块删除 rui-data 导入

创建 Nacos 配置文件

vim docs/backend/config-templates/nacos/rui-service-xxx.yaml

只写 server.port + 业务配置

推送 Nacos 并验证

检查清单

编辑前检查

本次修改是否涉及 application.yml 或 Nacos 配置？
是否在允许修改的范围内？
是否将业务配置放在了正确的位置？

编辑后检查

application.yml 是否仍与模板一致？
Nacos 配置是否未包含 application.yml 中已有的通用配置？
修改是否已同步到 Nacos 源文件和本地 application.yml（如适用）？
是否已按 Rule 4 推送后验证？

最后提醒：配置规范是为了保证 Nacos/本地配置的一致性和可维护性，请务必遵守！

6.9 KiB Raw Permalink Blame History Unescape Escape