Nacos配置中心使用规范

1. 关于Nacos引用方式

Nacos在Spring框架应用中使用方式共用4种：

1、nacos 原生引用方式

2、spring 引用方式

3、spring boot 引用方式

4、spring cloud 引用方式

每一种用法，略有差异，具体请参考Nacos官方文档：
Nacos 快速开始

---

2. 命名规范

2.1. 关于命名空间NameSpace的命名规范

命名空间NameSpace主要用于不同产品、不同平台，在配置管理上实现权限隔离，互不干扰。
命名格式规范：

{产品编码}-{环境名}

命名空间ID统一采用大写字母

{环境名} 为可选项，可以没有，如果有请使用拼音字母全拼

例如： JSCP、JSST、JSICP-HUANAN、JSICP-HUADONG

2.2. 关于Data ID的命名规范

2.2.1. 通用配置Data ID命名规范

命名格式规范：

{产品编码}-common-{配置特征名}.{文件类型}

配置特征名：即描述某一类配置共有的特征

2.2.2. 应用配置Data ID命名规范

应用配置相对于通用配置而言，专指应用独有的配置，不会也不应被其它应用使用的配置。
命名规范格式：

{应用服务名称}-{配置特征名}.{文件类型}

应用服务名称：即【spring.application.name】名称，同时也是微服务在注册中心的ID，具有唯一性。

Data ID 命名统一采用小写字母

例如：服务名为【jscp-jportal】 对应的应用配置data id为【jscp-jportal.properties】或者【jscp-jportal.yml】

---

2.3. 关于分组Group的命名规范

同一产品下的所有配置，在同一分组下，便于配置管理；
命名规范格式：

{分组名为产品编码}

Group分组名统一采用小写字母

例如：jscp、jsicp

2.4. 关于归属应用的命名规范

归属应用，不同于Group分组，通过分组可以快速找到某产品下所有的配置，但一个分组下包含了不同应用的配置，以及通用配置，如何快速找到某一应用下的所有配置？归属应用，应运而生。
命名规范格式：

{归属应用名为微服务名}

归属应用名与微服务名 【spring.application.name】 保持一致，同时也是微服务在注册中心的ID

2.5. 命名范例

以JLite为例，命名空间【JSICP-HUANAN】下的配置如下：

Data ID	Group	归属应用	备注
jsicp-common-mysql.yml	jsicp		通用配置
jsicp-common-redis.yml	jsicp		通用配置
jsicp-common-kafka.yml	jsicp		通用配置
jsicp-common-elasticsearch.yml	jsicp		通用配置
jsicp-common-hbase.yml	jsicp		通用配置
jsicp-common-mongodb.yml	jsicp		通用配置
jsicp-common-oss.yml	jsicp		通用配置
jsicp-common-constant.yml	jsicp		通用配置：常量
jlite-boot-starter.yml	jsicp	jlite-boot-starter	应用配置：jlite
jlite-boot-starter-messages_en_us.properties	jsicp	jlite-boot-starter	国际化配置-英文
jlite-boot-starter-messages_zh_cn.properties	jsicp	jlite-boot-starter	国际化配置-中文简体
jlite-boot-starter-messages_zh_tw.properties	jsicp	jlite-boot-starter	国际化配置-中文繁体
jlite-cloud-gateway.yml	jsicp	jlite-cloud-gateway	应用配置：网关
jlite-cloud-gateway-flow-rule.json	jsicp	jlite-cloud-gateway	应用配置：网关限流
jlite-cloud-gateway-api-group.json	jsicp	jlite-cloud-gateway	应用配置：网关API分组

注意： 为什么建议将通用配置，按照配置特征进行data-id区分，这样做更有利于配置的管理，可以清楚知道每一个微服务，具体用到了哪些配置项。

如果将所有通用配置放在一起，无论配置是否真正被使用到，配置文件都会被加载，当遇到技术栈升级时，比如需要对数据库密码策略进行更换，或者OSS账号密码泄漏需要更换账号。此时，在众多微服务中，哪些微服务应该重启？无法准确快速知道。

---

3. 关于启动配置文件的加载使用规范

spring boot构建的应用
启动时最先被加载的配置文件为：application.properties

spring cloud构建的应用
启动时最先被加载的配置文件为：bootstrap.properties

原则上本地配置文件：bootstrap.properties / application.properties 仅用于配置Nacos的地址、账号、日志文件存储位置等需要在启动后第一时间加载的参数。

4. 关于日志配置文件的使用规范

spring boot应用不再需要logback-spring.xml配置文件

日志文件如何配置？

4.1. 日志配置

【第一步】 bootstrap.yml

## 日志配置
logging:
  file:
    name: ./logs/${spring.application.name}.log
  level:
    org.springframework.boot.context.config.ConfigFileApplicationListener: debug # 生产上建议将该类的日志级别设为debug，这样可以清楚知道，启动时应用程序加载了哪些配置文件，分别从哪里加载的。

# 生产上建议将该类的日志级别设为debug，这样可以清楚知道，启动时应用程序加载了哪些配置文件，分别从哪里加载的。

该配置的作用是指定日志文件存储位置，必须放在bootstrap.yml文件中，因为需要保证在应用启动第一时间能读取到。

【第二步】 application.yml

## 日志配置
logging:
  file:
    max-history: 3  # 日志文件保留天数
    max-size: 200MB # 日志文件大小
  level:
    com.jht.jlite.gateway.filter.CustomGlobalFilter: debug
    com.jht.jlite.gateway.strategy.CustomStrategyRouteFilter: debug

以上配置，相比logback-spring.xml配置更加简洁，放在应用对应nacos配置中，可以动态修改生效。

 

5. 关于应用程序部署目录结构的规范

应用程序部署目录结构规范，以Jlite 网关为例：

|
---jlite-cloud-gateway
    |
    |
    |---jlite-cloud-gateway-1.0.1-RELEASE.jar # jar包排除配置文件
    |
    |---libdecrypt.so
    |
    |---manage.sh # 启动脚本中不再注入非JVM参数，统一移到bootstrap.yml
    |
    |---config
    |   |
    |   |---bootstrap.yml # 启动配置
    |   |
    |---config-example # 配置参考：在nacos上建立同名data-id
    |   |
    |   |---jlite-cloud-gateway.yml
    |   |
    |   |---jlite-cloud-gateway-api-group.json
    |   |
    |   |---jlite-cloud-gateway-flow-rule.json
    |   |
    |---logs # 日志文件默认目录，Docker容器化部署将该目录映射到宿主机即可
    |   |
    |   |

1. 为什么建议将jar包中的配置文件排除，这样做对于每一个配置项数据，在哪里进行配置（本地配置文件目录或配置中心），更加清晰，可见。便于问题的分析定位查找。
    

2. 启动脚本 manage.sh 文件中，不再注入除JVM参数以外的其它任何启动参数，相关参数(环境，版本号，Nacos地址、日志文件目录)统一放到配置文件 bootstrap.yml 中管理。

5.1. 打包时排除本地配置文件的方法

打包时，请将 src/main/resources 目录下所有配置文件排除在jar包之外。
具体排除方法，在pom.xml文件中添加plugin：

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <configuration>
                    <!-- 排除各类配置文件 -->
                    <excludes>
                        <exclude>*.yml</exclude>
                        <exclude>*.yaml</exclude>
                        <exclude>*.properties</exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

5.2. 打包时自动从Nacos下载配置文件

请在pom文件中添加nacos-maven-plugin插件，

该插件是我司自定义开发的maven插件，希望通过简单的配置，实现打包时自动从Nacos配置中心下载配置文件，解决打包时过多依赖人工处理的问题。配置将按Data ID生成同名文件，生成的文件目录为：target/config-example/

<!-- Nacos打包插件，用于下载配置文件 -->
<plugin>
    <groupId>com.js.nacos</groupId>
    <artifactId>nacos-maven-plugin</artifactId>
    <version>1.1.2</version>
    <!-- 可选参数，可以不配置 -->
    <configuration>
        <!-- skip 如果为true，将不会从nacos下载任何配置，默认为false -->
        <skip>true</skip>
        <server-addr>10.10.204.110:8848</server-addr>
        <namespace>billing-cloud</namespace>
        <user>app</user>
        <password>123456</password>
    </configuration>
    <executions>
        <execution>
            <!--插件运行所在生命周期-->
            <phase>package</phase>
            <goals>
                <!-- 插件目标名固定为：config-download -->
                <goal>config-download</goal>
            </goals>
        </execution>
    </executions>
</plugin>