digitalhainan-config ​

本文档用于指导在目标项目中完成 digitalhainan-config 模块集成。

执行顺序：

1. 先完成「3.1.2 快速集成」的全部步骤（必须）
2. 根据业务需求，查阅「功能集成决策索引」选择对应路径，逐项实现
3. 遇到配置问题时参考「3.1.3 配置属性参考」
4. 出现异常时查阅「3.1.6 常见问题」

代码约定： 所有代码示例均包含完整 import 路径和类声明，可直接用于代码生成。

3.1.1 模块简介 ​

digitalhainan-config 是数字海南框架的 Nacos 配置中心集成组件，提供：

• Nacos Config — 基于 Spring Cloud Alibaba Nacos Config 的配置中心集成
• Nacos Discovery — 服务注册与发现
• 早期配置加载 — NacosConfigLoader（SpringApplicationRunListener），在 Spring 容器启动前加载本地 YAML 配置
• YamlConfigReader — 提前读取 application.yml 配置（支持 Profile、环境变量、命令行参数）
• gRPC 端口偏移 — 支持 digitalhainan.component.nacos.grpc-offset 配置 Nacos gRPC 端口偏移

Maven 坐标：

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-config</artifactId>
</dependency>

前置依赖：

当前版本： 3.1.0-SNAPSHOT

3.1.2 快速集成 ​

3.1.2.1 确认父 POM ​

<parent>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-pom</artifactId>
    <version>3.1.0-SNAPSHOT</version>
</parent>

3.1.2.2 添加依赖 ​

<dependencies>
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>digitalhainan-config</artifactId>
    </dependency>
</dependencies>

3.1.2.3 配置 Nacos 连接（bootstrap.yml 或 application.yml） ​

spring:
  application:
    name: your-service-name
  cloud:
    nacos:
      # 配置中心
      config:
        server-addr: 192.168.1.100:8848
        namespace: your-namespace-id
        group: DEFAULT_GROUP
        file-extension: yaml
      # 服务发现
      discovery:
        server-addr: 192.168.1.100:8848
        namespace: your-namespace-id

3.1.2.4 验证清单 ​

• [ ] Spring Boot 启动成功连接 Nacos
• [ ] 配置中心配置可拉取
• [ ] 服务注册成功

3.1.3 配置属性参考 ​

3.1.3.1 框架自定义配置 ​

3.1.3.2 Nacos Config 配置 ​

spring:
  cloud:
    nacos:
      config:
        server-addr: 192.168.1.100:8848   # Nacos 服务地址
        namespace: your-namespace-id       # 命名空间 ID
        group: DEFAULT_GROUP               # 配置分组
        file-extension: yaml               # 配置文件格式
        prefix: ${spring.application.name} # 配置文件名前缀
        shared-configs:                    # 共享配置（可选）
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true

3.1.3.3 Nacos Discovery 配置 ​

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 192.168.1.100:8848
        namespace: your-namespace-id
        group: DEFAULT_GROUP

3.1.4 核心功能使用 ​

功能集成决策索引 ​

3.1.4.1 Nacos 配置中心 ​

在 Nacos 控制台创建配置文件（Data ID: your-service-name.yaml），内容示例：

server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_db

应用启动后自动拉取 Nacos 配置，支持动态刷新（@RefreshScope）。

3.1.4.2 gRPC 端口偏移 ​

当 Nacos 2.x gRPC 端口（默认 9848）被占用时：

digitalhainan:
  component:
    nacos:
      grpc-offset: 1000  # gRPC 端口偏移 1000，实际 gRPC 端口 = 9848 + 1000 = 10848

3.1.4.3 YamlConfigReader — 早期配置读取 ​

package com.example.config;

import cn.com.digitalhainan.nacos.config.common.YamlConfigReader;

/**
 * YamlConfigReader 使用示例
 * 在 Spring 容器初始化之前读取 application.yml 中的配置
 */
public class EarlyConfigDemo {

    public void readConfig() {
        // 读取字符串配置
        String appName = YamlConfigReader.getProperty("spring.application.name");

        // 读取带默认值的配置
        Integer port = YamlConfigReader.getProperty("server.port", 8080);

        // 获取当前激活的 Profile
        var profiles = YamlConfigReader.getActiveProfiles();

        // 检查是否包含某个 Profile
        boolean isDev = YamlConfigReader.hasProfile("dev");
    }
}

3.1.5 版本变更记录 ​

v3.1.0（当前版本） ​

• 适配 Nacos 配置
• 支持 gRPC 端口偏移

v3.0.1 ​

• 初始化 3.0.1

v3.0.0 ​

• Spring Boot 3.x 适配
• 支持配置偏移量

v2.1.0 ​

• 升级 2.1.0

v2.0.0 ​

• 新增服务发现

3.1.6 常见问题 ​

Q1：启动报错 "Nacos connection refused"？ ​

原因： Nacos 服务地址配置错误或 Nacos 未启动。 解决： 检查 spring.cloud.nacos.config.server-addr 配置。

Q2：Nacos 配置未生效？ ​

原因： 配置文件 Data ID 与应用名不匹配，或 namespace/group 不正确。 解决： 确保 Nacos 中的 Data ID 为 {spring.application.name}.{file-extension}，namespace 和 group 一致。

Q3：gRPC 端口冲突？ ​

原因： Nacos 2.x 默认 gRPC 端口为 server-addr 端口 + 1000，可能与已有服务冲突。 解决： 配置 digitalhainan.component.nacos.grpc-offset 调整偏移量。

3.1.7 版本兼容性矩阵 ​