Nacos配置管理案例

wen java案例 2026-08-04 1

本文目录导读：

Nacos配置管理案例

案例背景与架构
环境准备
核心步骤
案例测试：动态刷新演示
进阶场景：多配置共享与优先级
常见问题排查

Nacos（Dynamic Naming and Configuration Service）是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台，在Spring Cloud项目中，它常被用作配置中心。

这里为你提供一个完整的Nacos配置管理实战案例，从环境准备到动态刷新,涵盖最常用的场景。

案例背景与架构

目标：模拟微服务中的“订单服务”(order-service)。
需求：
1. 将数据库连接信息、日志级别等配置从本地application.yml中剥离，放到Nacos Server中统一管理。
2. 在不重启服务的情况下，修改Nacos中的日志级别，应用能自动生效（动态刷新）。
技术栈：Spring Boot 2.x / 3.x + Spring Cloud Alibaba + Nacos Server 2.x。

环境准备

启动 Nacos Server：下载并启动Nacos（默认为8848端口，控制台地址为http://localhost:8848/nacos，默认账号密码为nacos/nacos）。
创建命名空间（可选）：为了隔离环境（如开发/测试/生产），在控制台创建一个命名空间（dev），并记住其命名空间ID（例如生成的UUID字符串）。

核心步骤

添加依赖

在order-service的pom.xml中添加以下依赖：

<!-- Nacos 配置中心客户端 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    <version>2021.1</version> <!-- 或与你的Spring Cloud Alibaba版本匹配 -->
</dependency>
<!-- Spring Boot 基础依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

配置文件辨析与编写

这是关键的区分点：Nacos配置中心要求应用在启动时必须先通过bootstrap.yml或spring.config.import去Nacos拉取配置，因此不能把Nacos地址写在application.yml中。

bootstrap.yml（负责连接Nacos机制）

在src/main/resources目录下创建bootstrap.yml：

spring:
  application:
    name: order-service # 微服务名称，也是Nacos中配置的数据ID的一部分
  cloud:
    nacos:
      config:
        server-addr: localhost:8848 # Nacos服务器地址
        file-extension: yaml # 文件后缀格式（即Nacos中的后缀）
        namespace: YOUR_NAMESPACE_ID # 如果使用默认public，可以省略这行
        group: DEFAULT_GROUP
        refresh-enabled: true # 开启动态刷新

application.yml（仅保留非Nacos管理项）

server:
  port: 8081
# 注意：这里不建议写数据库配置和自定义配置了，全部由Nacos覆盖

在 Nacos 控制台创建配置文件

登录Nacos控制台 -> 配置管理 -> 配置列表 -> 选择命名空间（dev） -> 新建配置。

配置详情： Data ID：order-service.yaml（格式为：${spring.application.name}.${file-extension}） Group：DEFAULT_GROUP 配置格式：选择 YAML 核心演示）**：

# 数据库连接配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/order_db?useUnicode=true&characterEncoding=utf8&useSSL=false
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
# 自定义配置项（用于演示动态刷新）
app:
  config:
    info: "这是来自Nacos的配置信息 v1.0"
# 日志级别（演示动态刷新）
logging:
  level:
    com.example.order: debug # 将包名下的日志级别设为debug

编写业务代码验证

创建一个配置读取类，使用@RefreshScope注解来支持动态刷新。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
// 关键注解：标记该Bean在Nacos配置更新后会重新代理刷新
@RefreshScope
public class ConfigController {
    // 读取Nacos中配置的 app.config.info
    @Value("${app.config.info:默认值}")
    private String appInfo;
    // 读取数据库URL（我们会将其打印出来，验证是否来自Nacos）
    // 注意：为了简便，这里不做代码硬编码，从环境变量中读取演示
    @Value("${spring.datasource.url}")
    private String dbUrl;
    @GetMapping("/config/info")
    public String getConfig() {
        StringBuilder sb = new StringBuilder();
        sb.append("读取Nacos配置内容：").append(appInfo);
        sb.append("<br/>数据库连接：").append(dbUrl);
        return sb.toString();
    }
}

注意：如果你不想在Controller中注入@Value，也可以使用@ConfigurationProperties配合@RefreshScope使用。

案例测试：动态刷新演示

这是Nacos配置中心最大的亮点之一。

服务启动：运行OrderServiceApplication主类。
第一次访问：浏览器访问 http://localhost:8081/config/info。预期结果：
```
读取Nacos配置内容：这是来自Nacos的配置信息 v1.0
数据库连接：jdbc:mysql://localhost:3306/order_db?...
```
这证明了配置成功从Nacos拉取。
修改Nacos配置 回到Nacos控制台，将配置内容中的app.config.info改为“这是来自Nacos的配置信息 v2.0”，点击发布。
第二次访问（不重启应用） 再次访问 http://localhost:8081/config/info。预期结果：无需重启应用，页面显示内容自动变为v2.0。

原因分析：@RefreshScope + Nacos的refresh-enabled: true机制,监听到配置变更后自动刷新了Spring容器中的Bean。

进阶场景：多配置共享与优先级

在实际架构中，不会只有一个服务，通常会有公共配置（如日志框架、通用依赖）,Nacos支持共享配置。

场景：多个服务共用同一个common.yaml。

# bootstrap.yml 修改
spring:
  cloud:
    nacos:
      config:
        # 共享配置（数组形式，支持多个）
        shared-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true

配置优先级（从高到低）： Spring Cloud 应用名称的配置 > 扩展配置 (extension-configs) > 共享配置 (shared-configs) > 本地 application.yml。

常见问题排查

启动报错：Nacos config not found
- 检查spring.application.name是否与Data ID前缀一致。
- 检查file-extension是否与Data ID后缀一致（注意Data ID是xxx.yaml，后缀就是yaml）。
- 检查namespace是否填写正确，如果使用默认空间，不要在bootstrap.yml中填写namespace,或者留空。
配置修改了但客户端没刷新
- 确认引用该配置的类（或方法）是否被@RefreshScope注解修饰。
- 确认监听的是否是同一个Data ID和Group。
特殊字符问题
Nacos控制台编辑配置时，不要使用Tab键,请使用空格缩进。

通过这个案例，你可以看到Nacos配置管理的主要流程： 服务启动 -> 加载bootstrap.yml -> 连接Nacos -> 拉取目标Data ID配置 -> 与本地配置合并 -> 业务加载。

核心点在于动态刷新（@RefreshScope）和环境隔离（namespace）,这是微服务架构中降本增效的重要工具。