1. 版本兼容性说明
1.1 版本对应关系
| 组件 | 版本 | 说明 |
|---|---|---|
| Spring Boot | 3.2.x | JDK 17+ 要求 |
| Spring Cloud | 2023.0.x (aka 2024) | 对应 Spring Boot 3.2.x |
| Spring Cloud Alibaba | 2022.0.0.0 | 对应 Spring Cloud 2023.0.x |
| Nacos Client | 2.2.x | Spring Cloud Alibaba 自动管理 |
| Nacos Server | 2.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 配置组织原则
- 环境隔离:使用 Nacos 命名空间或 Group 隔离不同环境
- 配置分层:
- 共享配置:
common-config.yaml - 应用配置:
{app-name}.yaml - 环境配置:
{app-name}-{profile}.yaml
- 共享配置:
- 敏感信息:绝不硬编码,使用环境变量或加密
- 版本控制:Nacos 配置变更应有审计和回滚机制
10.2 Spring Boot 3 + Nacos 最佳实践
- 使用新配置导入方式:
spring.config.import替代 bootstrap.yml - 合理使用 optional:开发环境使用
optional:,生产环境不使用 - 启用配置刷新:使用
@RefreshScope支持动态配置更新 - 监控和告警:配置变更应有监控和通知机制
10.3 性能和可靠性
- 连接池配置:合理配置 Nacos 客户端连接池
- 重试机制:配置适当的重试策略
- 本地缓存:Nacos 客户端会自动缓存配置到本地文件
- 降级策略:配置中心不可用时的降级处理
通过遵循这些最佳实践,您可以构建一个安全、可靠、可维护的基于 Spring Boot 3 + Spring Cloud 2024 + Nacos 的配置管理体系。

6027

被折叠的 条评论
为什么被折叠?



