Spring Boot 3 + Spring Cloud 2024 + Nacos 配置中心完整指南

【投稿赢 iPhone 17】「我的第一个开源项目」故事征集:用代码换C位出道! 10w+人浏览 1.6k人参与

1. 版本兼容性说明

1.1 版本对应关系

组件版本说明
Spring Boot3.2.xJDK 17+ 要求
Spring Cloud2023.0.x (aka 2024)对应 Spring Boot 3.2.x
Spring Cloud Alibaba2022.0.0.0对应 Spring Cloud 2023.0.x
Nacos Client2.2.xSpring Cloud Alibaba 自动管理
Nacos Server2.2.x 或 2.3.x推荐使用最新稳定版

1.2 重要变化

  • Spring Boot 3:移除了 bootstrap.yml 默认支持,完全推荐使用 spring.config.import
  • Spring Cloud 2023.0:进一步强化了新配置导入机制
  • Spring Cloud Alibaba 2022.0.0.0:完全适配 Spring Boot 3 和新配置机制

1.3 Spring Cloud Alibaba 特别说明

  • Spring Cloud Alibaba:2023.0.1.3 及以上版本 spring.cloud.nacos.config.shared-configs、extension-configs 以及默认加载的 application.name 配置已经废弃, 以上版本请统一使用 spring.config.import 方式导入 Nacos 配置,见issue #3998
  • Spring Cloud 2023:bootstrap.yml 以及 bootstrap.properties 已不推荐使用,请使用 application.yml 或者 application.properties

2. 项目依赖配置

2.1 Maven 依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>nacos-config-demo</artifactId>
    <version>1.0.0</version>
    <name>nacos-config-demo</name>

    <properties>
        <java.version>17</java.version>
        <spring-cloud.version>2023.0.0</spring-cloud.version>
        <spring-cloud-alibaba.version>2022.0.0.0</spring-cloud-alibaba.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Cloud 依赖管理 -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            
            <!-- Spring Cloud Alibaba 依赖管理 -->
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Spring Boot Web Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot Actuator -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Spring Cloud Alibaba Nacos Config -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        </dependency>

        <!-- Spring Cloud Alibaba Nacos Discovery (可选,如果需要服务发现) -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <!-- Spring Cloud 负载均衡,为服务发现提供负载均衡 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-loadbalancer</artifactId>
        </dependency>

        <!-- Configuration Processor (用于 @ConfigurationProperties 提示) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Lombok (可选) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

2.2 Gradle 依赖

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '1.0.0'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

ext {
    set('springCloudVersion', "2023.0.0")
    set('springCloudAlibabaVersion', "2022.0.0.0")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-config'
    implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-discovery'
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
        mavenBom "com.alibaba.cloud:spring-cloud-alibaba-dependencies:${springCloudAlibabaVersion}"
    }
}

3. Nacos 配置中心配置文件组织

3.1 配置文件命名规范

Nacos 中的配置文件命名遵循以下规则:

${spring.application.name}-${spring.profiles.active}.${file-extension}

示例

  • 应用名称:user-service
  • 环境:dev
  • 文件格式:yaml

Nacos 配置文件名user-service-dev.yaml

3.2 Nacos 配置管理界面设置

在 Nacos 控制台中创建配置:

  • Data ID: user-service-dev.yaml
  • Group: DEFAULT_GROUP (或自定义分组)
  • 配置格式: YAML
  • 配置内容: YAML 格式的配置内容

3.3 本地配置文件结构

src/main/resources/
├── application.yml           # 公共配置(Nacos 未覆盖的配置)
├── application-dev.yml       # 开发环境本地配置
├── application-test.yml      # 测试环境本地配置  
├── application-staging.yml   # 预发布环境本地配置
└── application-prod.yml      # 生产环境本地配置

4. 详细配置文件示例

4.1 application.yml(主配置文件)

# application.yml - 主应用配置文件
# 说明:包含应用的基础配置和 Nacos 连接信息
# 注意:Spring Boot 3 + Spring Cloud 2024 使用 spring.config.import 方式

# 应用基本信息
spring:
  application:
    name: user-service

  # Nacos 配置中心配置(基础连接信息)
  cloud:
    # 负载均衡配置
    loadbalancer:
      nacos:
        enabled: true
    nacos:
      # Nacos 服务器地址
      server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
      # 用户名和密码(如果 Nacos 启用了认证)
      username: ${NACOS_USERNAME:nacos}
      password: ${NACOS_PASSWORD:nacos}

      # 配置中心特定配置
      config:
        # 是否启用配置中心
        enabled: true
        # 配置中心文件配置是否支持动态刷新
        refresh-enabled: true
        # 命名空间(可选,用于环境隔离)
        namespace: ${NACOS_NAMESPACE:}
        # 配置分组
        group: DEFAULT_GROUP
        # 配置文件扩展名
        file-extension: yaml
        # 文件编码
        encode: UTF-8
        # 配置超时时间(毫秒)
        timeout: 3000
        # 最大重试次数
        max-retry: 3
        # 重试间隔(毫秒)
        config-retry-time: 2000
        # 是否启用配置监听
        enable-remote-sync-config: true
        # 配置导入(Spring Boot 3 新方式)
        import-check:
          enabled: true

      # 服务发现配置(如果使用)
      discovery:
        # 是否启用服务发现
        enabled: true
        # 命名空间(可选,用于环境隔离)
        namespace: ${NACOS_NAMESPACE:}
        # 服务分组
        group: DEFAULT_GROUP

  # 配置导入(关键!Spring Boot 3 的新方式)
  config:
    import:
      # 导入 Nacos 配置
      - optional:nacos:${spring.application.name}.yaml
      # 导入环境特定的 Nacos 配置
      - optional:nacos:${spring.application.name}-${spring.profiles.active:default}.yaml
      # 导入共享配置
      - optional:nacos:common-config.yaml
      - optional:nacos:application.yaml?group=DEFAULT_GROUP&refreshable=true

# 服务器配置
server:
  port: 8080
  servlet:
    context-path: /api

# Actuator 配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,configprops,env,refresh
  endpoint:
    health:
      show-details: always

# 日志配置
logging:
  level:
    root: INFO
    com.example: DEBUG
    com.alibaba.nacos: WARN

# 自定义业务配置(会被 Nacos 配置覆盖)
user:
  service:
    cache-expire-time: 3600
    max-registration-count: 10000
    enable-email-verification: true

4.2 application-dev.yml(开发环境配置)

# application-dev.yml - 开发环境配置文件
# 说明:开发环境特定配置,Nacos 中的同名配置会覆盖此文件

spring:
  profiles:
    active: dev
  
  # 开发环境 Nacos 配置
  cloud:
    nacos:
      server-addr: localhost:8848
      config:
        namespace: dev-namespace  # 开发环境命名空间
        group: DEV_GROUP
        file-extension: yaml

  # 配置导入(环境特定)
  config:
    import:
      - optional:nacos:${spring.application.name}-dev.yaml
      - optional:nacos:common-config-dev.yaml

# 服务器配置
server:
  port: 8081

# 开发环境数据库配置(会被 Nacos 覆盖)
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/user_db_dev
    username: dev_user
    password: dev_password

# 开发环境自定义配置
user:
  service:
    cache-expire-time: 60      # 开发环境短缓存
    enable-email-verification: false  # 开发环境不启用邮箱验证

# 开发环境日志
logging:
  level:
    root: DEBUG
    com.example: DEBUG
    org.springframework.web: DEBUG

4.3 application-test.yml(测试环境配置)

# application-test.yml - 测试环境配置文件

spring:
  profiles:
    active: test
  
  cloud:
    nacos:
      server-addr: test-nacos:8848
      config:
        namespace: test-namespace
        group: TEST_GROUP
        file-extension: yaml

  config:
    import:
      - optional:nacos:${spring.application.name}-test.yaml
      - optional:nacos:common-config-test.yaml

# 测试环境服务器配置
server:
  port: 8082

# 测试环境数据源(使用 H2 内存数据库)
spring:
  datasource:
    driver-class-name: org.h2.Driver
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
    username: sa
    password: 

# 测试环境自定义配置
user:
  service:
    cache-expire-time: 10      # 测试环境极短缓存
    max-registration-count: 999999
    enable-email-verification: false

# 测试环境日志
logging:
  level:
    root: INFO
    com.example: DEBUG
    org.springframework.test: DEBUG

4.4 application-staging.yml(预发布环境配置)

# application-staging.yml - 预发布环境配置文件

spring:
  profiles:
    active: staging
  
  cloud:
    nacos:
      server-addr: staging-nacos-cluster:8848
      username: ${NACOS_STAGING_USERNAME}
      password: ${NACOS_STAGING_PASSWORD}
      config:
        namespace: staging-namespace
        group: STAGING_GROUP
        file-extension: yaml

  config:
    import:
      - nacos:${spring.application.name}-staging.yaml  # 非 optional,必须存在
      - nacos:common-config-staging.yaml

# 预发布环境服务器配置
server:
  port: 8080
  ssl:
    enabled: true
    key-store: classpath:staging-keystore.p12
    key-store-password: ${SSL_KEYSTORE_PASSWORD}

# 预发布环境自定义配置
user:
  service:
    cache-expire-time: 3600    # 1小时缓存
    max-registration-count: 500000
    enable-email-verification: true

# 预发布环境日志
logging:
  level:
    root: INFO
    com.example: INFO

4.5 application-prod.yml(生产环境配置)

# application-prod.yml - 生产环境配置文件

spring:
  profiles:
    active: prod
  
  cloud:
    nacos:
      server-addr: ${NACOS_PROD_SERVER_ADDR}  # 从环境变量获取
      username: ${NACOS_PROD_USERNAME}
      password: ${NACOS_PROD_PASSWORD}
      config:
        namespace: ${NACOS_PROD_NAMESPACE}
        group: PROD_GROUP
        file-extension: yaml
        timeout: 5000
        max-retry: 5

  config:
    import:
      - nacos:${spring.application.name}-prod.yaml  # 必须存在
      - nacos:common-config-prod.yaml

# 生产环境服务器配置
server:
  port: 8080
  servlet:
    context-path: /api
  tomcat:
    max-threads: 500
    min-spare-threads: 25
    connection-timeout: 10000

# 生产环境自定义配置
user:
  service:
    cache-expire-time: 7200    # 2小时缓存
    max-registration-count: 1000000
    enable-email-verification: true

# 生产环境 Actuator(严格限制)
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: when_authorized

# 生产环境日志
logging:
  level:
    root: WARN
    com.example: INFO
  file:
    name: /var/log/user-service/user-service.log
    max-size: 100MB
    max-history: 90

5. Nacos 配置中心中的配置示例

5.1 user-service-dev.yaml(Nacos 中)

# Nacos 配置:user-service-dev.yaml
# Group: DEV_GROUP
# Namespace: dev-namespace

# 数据源配置(覆盖本地配置)
spring:
  datasource:
    url: jdbc:mysql://dev-mysql-cluster:3306/user_db_dev
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

# Redis 配置
spring:
  redis:
    host: dev-redis-cluster
    port: 6379
    database: 1
    timeout: 2000

# 业务配置(覆盖本地配置)
user:
  service:
    cache-expire-time: 300    # 5分钟缓存(覆盖本地的60秒)
    sms-api-url: https://dev-sms-api.example.com
    sms-api-key: ${SMS_API_KEY}

# 第三方服务配置
third-party:
  payment:
    gateway-url: https://dev-payment-gateway.example.com
    merchant-id: dev-merchant-123

5.2 user-service-prod.yaml(Nacos 中)

# Nacos 配置:user-service-prod.yaml
# Group: PROD_GROUP  
# Namespace: prod-namespace

# 生产数据源配置
spring:
  datasource:
    url: jdbc:mysql://prod-mysql-cluster:3306/user_db_prod?useSSL=true
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 50
      minimum-idle: 10
      connection-timeout: 20000
      idle-timeout: 300000
      max-lifetime: 1200000

# 生产 Redis 配置
spring:
  redis:
    cluster:
      nodes:
        - prod-redis-1:7000
        - prod-redis-2:7001  
        - prod-redis-3:7002
    timeout: 2000
    lettuce:
      pool:
        max-active: 20
        max-idle: 10

# 生产业务配置
user:
  service:
    cache-expire-time: 7200    # 2小时缓存
    max-registration-count: 10000000
    enable-email-verification: true
    email-verification-expire-hours: 48
    sms-api-url: https://prod-sms-api.example.com
    sms-api-key: ${SMS_API_KEY}

# 安全配置
security:
  jwt:
    secret: ${JWT_SECRET}
    expiration: 259200000  # 3天

# 监控配置
monitoring:
  apm:
    enabled: true
    server-url: https://prod-apm.example.com

5.3 common-config.yaml(Nacos 共享配置)

# Nacos 配置:common-config.yaml
# Group: DEFAULT_GROUP
# 适用于所有环境的共享配置

# 公共业务配置
app:
  version: 1.0.0
  build-time: ${BUILD_TIME}
  contact-email: support@example.com

# 公共第三方服务配置
third-party:
  common:
    timeout: 5000
    retry:
      max-attempts: 3
      backoff-multiplier: 2.0

# 公共安全配置
security:
  cors:
    allowed-origins:
      - https://example.com
      - https://www.example.com
    allowed-methods:
      - GET
      - POST
      - PUT
      - DELETE
    allowed-headers: "*"
    allow-credentials: true

6. 高级配置特性

6.1 配置动态刷新

6.1.1 使用 @RefreshScope
@RestController
@RefreshScope  // 支持配置动态刷新
public class UserController {
    
    @Value("${user.service.cache-expire-time}")
    private int cacheExpireTime;
    
    @Value("${user.service.max-registration-count}")
    private int maxRegistrationCount;
    
    @GetMapping("/config")
    public Map<String, Object> getConfig() {
        Map<String, Object> config = new HashMap<>();
        config.put("cacheExpireTime", cacheExpireTime);
        config.put("maxRegistrationCount", maxRegistrationCount);
        return config;
    }
}
6.2.2 使用 @ConfigurationProperties
@Data
@Component
@ConfigurationProperties(prefix = "user.service")
@RefreshScope  // 支持动态刷新
public class UserServiceProperties {
    
    private int cacheExpireTime = 3600;
    
    private int maxRegistrationCount = 10000;
    
    private boolean enableEmailVerification = true;
    
    private int emailVerificationExpireHours = 24;
    
    private String smsApiUrl;
    
    private String smsApiKey;
}
6.2.3 手动触发刷新
# POST 请求触发配置刷新
curl -X POST http://localhost:8080/actuator/refresh

# 返回被刷新的属性列表
["user.service.cache-expire-time", "user.service.max-registration-count"]

6.3 配置监听器

@Component
public class NacosConfigListener {
    
    private static final Logger log = LoggerFactory.getLogger(NacosConfigListener.class);
    
    @EventListener
    public void handleConfigChangeEvent(RefreshScopeRefreshedEvent event) {
        log.info("配置已刷新: {}", event);
        // 执行自定义逻辑
    }
    
    // 或者监听具体的配置变化
    @EventListener
    public void handleEnvironmentChangeEvent(EnvironmentChangeEvent event) {
        Set<String> changedKeys = event.getKeys();
        log.info("变化的配置项: {}", changedKeys);
    }
}

7. 安全配置最佳实践

7.1 敏感信息处理

# ❌ 错误做法:硬编码敏感信息
spring:
  datasource:
    password: "hardcoded_password"

# ✅ 正确做法:使用环境变量
spring:
  datasource:
    password: ${DB_PASSWORD}

# ✅ 更好的做法:使用 Nacos 的加密功能
spring:
  datasource:
    password: ENC(encrypted_password_here)

7.2 Nacos 认证配置

# application.yml
spring:
  cloud:
    nacos:
      server-addr: ${NACOS_SERVER_ADDR}
      # 启用认证
      username: ${NACOS_USERNAME}
      password: ${NACOS_PASSWORD}
      # 或使用 AccessKey/SecretKey
      access-key: ${NACOS_ACCESS_KEY}
      secret-key: ${NACOS_SECRET_KEY}

7.3 配置加密

// 配置解密处理器
@Configuration
public class EncryptionConfig {
    
    @Bean
    public TextEncryptor textEncryptor() {
        // 使用 Jasypt 或其他加密库
        return new AesTextEncryptor("encryption-key");
    }
}

8. 部署和运维

8.1 Docker 环境变量配置

# Dockerfile
FROM openjdk:17-jdk-slim

COPY target/user-service.jar app.jar

ENV NACOS_SERVER_ADDR=nacos-cluster:8848
ENV NACOS_NAMESPACE=prod-namespace  
ENV DB_PASSWORD=your-db-password
ENV JWT_SECRET=your-jwt-secret

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app.jar"]

8.2 启动参数覆盖

# 命令行参数优先级最高
java -jar user-service.jar \
  --spring.profiles.active=prod \
  --spring.cloud.nacos.server-addr=prod-nacos:8848 \
  --user.service.cache-expire-time=1800

9. 故障排查和监控

9.1 配置加载日志

# 启用详细日志
logging:
  level:
    com.alibaba.nacos: DEBUG
    org.springframework.cloud.bootstrap: DEBUG
    org.springframework.boot.context.config: DEBUG

9.2 Actuator 端点

# 查看所有配置属性
GET /actuator/env

# 查看特定属性
GET /actuator/env/user.service.cache-expire-time

# 查看配置属性源
GET /actuator/configprops

# 查看 Nacos 配置状态
GET /actuator/nacosconfig

9.3 健康检查

@Component
public class NacosConfigHealthIndicator extends AbstractHealthIndicator {
    
    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        // 检查 Nacos 连接状态
        if (nacosConfigService.isConnected()) {
            builder.up().withDetail("status", "connected");
        } else {
            builder.down().withDetail("status", "disconnected");
        }
    }
}

10. 总结和最佳实践

10.1 配置组织原则

  1. 环境隔离:使用 Nacos 命名空间或 Group 隔离不同环境
  2. 配置分层
    • 共享配置:common-config.yaml
    • 应用配置:{app-name}.yaml
    • 环境配置:{app-name}-{profile}.yaml
  3. 敏感信息:绝不硬编码,使用环境变量或加密
  4. 版本控制:Nacos 配置变更应有审计和回滚机制

10.2 Spring Boot 3 + Nacos 最佳实践

  1. 使用新配置导入方式spring.config.import 替代 bootstrap.yml
  2. 合理使用 optional:开发环境使用 optional:,生产环境不使用
  3. 启用配置刷新:使用 @RefreshScope 支持动态配置更新
  4. 监控和告警:配置变更应有监控和通知机制

10.3 性能和可靠性

  1. 连接池配置:合理配置 Nacos 客户端连接池
  2. 重试机制:配置适当的重试策略
  3. 本地缓存:Nacos 客户端会自动缓存配置到本地文件
  4. 降级策略:配置中心不可用时的降级处理

通过遵循这些最佳实践,您可以构建一个安全、可靠、可维护的基于 Spring Boot 3 + Spring Cloud 2024 + Nacos 的配置管理体系。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

龙茶清欢

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值