Spring Boot 3.x 整合 Nacos 全栈实战教程

Nacos 是阿里巴巴开源的一款功能强大的动态服务发现、配置管理和服务管理平台。在微服务架构中它扮演着“注册中心”和“配置中心”的双重角色完美替代了 Eureka 和 Spring Cloud Config。本教程将基于Spring Boot 3.x和Spring Cloud Alibaba 2022.x手把手教你如何从零搭建 Nacos 环境并实现服务的注册发现与配置的动态刷新。环境准备与 Nacos 服务端启动在开始编写代码之前我们需要先拥有一个运行中的 Nacos 服务端。下载 Nacos访问 Nacos 官方 GitHub 发布页下载最新稳定版如 2.x 版本的压缩包并解压。单机模式启动Nacos 默认是以集群模式启动的如果是本地学习或开发测试必须指定为单机模式否则会因找不到集群配置而启动失败。进入 Nacos 的bin目录执行以下命令Windows:startup.cmd -m standaloneLinux/Mac:sh startup.sh -m standalone访问控制台启动成功后打开浏览器访问http://127.0.0.1:8848/nacos。默认账号:nacos默认密码:nacos核心依赖与基础配置我们将创建一个标准的 Spring Boot 项目并引入 Nacos 的相关依赖。Maven 依赖确保你的pom.xml中包含以下核心依赖。注意版本管理这里使用的是 Spring Cloud Alibaba 的 Starter。dependencies!-- Nacos 服务发现依赖 --dependencygroupIdcom.alibaba.cloud/groupIdartifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId/dependency!-- Nacos 配置中心依赖 --dependencygroupIdcom.alibaba.cloud/groupIdartifactIdspring-cloud-starter-alibaba-nacos-config/artifactId/dependency!-- Web 依赖 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Actuator 用于刷新配置可选但推荐 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-actuator/artifactId/dependency/dependenciesdependencyManagementdependencies!-- 引入 Spring Cloud Alibaba 的版本管理 --dependencygroupIdcom.alibaba.cloud/groupIdartifactIdspring-cloud-alibaba-dependencies/artifactIdversion2022.0.0.0/version!-- 请根据 Spring Boot 版本选择对应版本 --typepom/typescopeimport/scope/dependency/dependencies/dependencyManagement配置 bootstrap.yml这是最关键的一步。为了让 Nacos 配置中心在应用启动的早期阶段生效必须将 Nacos 的连接配置写在bootstrap.yml或bootstrap.properties中而不是application.yml中。因为bootstrap的加载优先级高于application。spring:application:name:nacos-demo-service# 服务名也是 Nacos 中 Data ID 的前缀cloud:nacos:# 配置中心地址config:server-addr:127.0.0.1:8848file-extension:yaml# 配置文件格式# namespace: public # 如果需要隔离环境填写命名空间 ID# group: DEFAULT_GROUP # 默认分组# 服务注册中心地址discovery:server-addr:127.0.0.1:8848# 暴露刷新端点用于手动触发配置刷新如果不使用自动刷新management:endpoints:web:exposure:include:refresh实战一配置中心与动态刷新我们将演示如何从 Nacos 获取配置并在不重启服务的情况下动态修改配置。在 Nacos 控制台发布配置登录 Nacos 控制台进入“配置管理” - “配置列表”。点击“”号新建配置。Data ID:nacos-demo-service.yaml必须与spring.application.namefile-extension对应。配置内容:message:Hello from Nacos Config!feature-enabled:true点击“发布”。编写代码读取配置使用RefreshScope注解是实现配置热更新的关键。当 Nacos 中的配置发生变化时Spring 容器会自动重新注入最新的值。importorg.springframework.beans.factory.annotation.Value;importorg.springframework.cloud.context.config.annotation.RefreshScope;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;RestControllerRefreshScope// 开启配置动态刷新publicclassConfigController{Value(${message:Default Message})privateStringmessage;Value(${feature-enabled:false})privatebooleanfeatureEnabled;GetMapping(/config)publicStringgetConfig(){return当前配置: message, 功能开关: featureEnabled;}}验证效果启动应用访问http://localhost:8080/config你会看到 Nacos 中的配置内容。回到 Nacos 控制台修改message的值为 “Hello World Updated!” 并发布。无需重启应用再次刷新浏览器接口你会发现配置已经实时生效。实战二服务注册与发现接下来我们将演示如何让服务注册到 Nacos并让另一个服务发现它。服务提供者假设我们有一个user-service它只需要配置好discovery依赖和地址启动后就会自动注册到 Nacos。// 启动类SpringBootApplicationEnableDiscoveryClient// 开启服务发现Spring Cloud Alibaba 中通常可省略自动生效publicclassUserServiceApplication{publicstaticvoidmain(String[]args){SpringApplication.run(UserServiceApplication.class,args);}}启动后在 Nacos 控制台的“服务管理” - “服务列表”中你应该能看到user-service。服务消费者消费者通过DiscoveryClient或RestTemplate来调用提供者。importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.cloud.client.ServiceInstance;importorg.springframework.cloud.client.discovery.DiscoveryClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;importorg.springframework.web.client.RestTemplate;importjava.util.List;RestControllerpublicclassConsumerController{AutowiredprivateDiscoveryClientdiscoveryClient;AutowiredprivateRestTemplaterestTemplate;GetMapping(/call-user)publicStringcallUserService(){// 1. 从 Nacos 获取名为 user-service 的所有实例ListServiceInstanceinstancesdiscoveryClient.getInstances(user-service);if(instances.isEmpty()){return没有找到可用的用户服务;}// 2. 获取第一个实例的地址ServiceInstanceinstanceinstances.get(0);Stringurlinstance.getUri()/user/info;// 假设提供者有这个接口// 3. 发起调用return调用结果: restTemplate.getForObject(url,String.class);}}常见坑点与排查配置无法加载检查bootstrap.yml是否写错成了application.yml。检查 Nacos 中的 Data ID 是否与代码中的spring.application.name完全一致。检查file-extension是否匹配如 Nacos 中是.yaml配置里也要写yaml。服务注册不上检查 Nacos 服务端是否真的启动成功查看日志。检查server-addr端口是否被防火墙拦截。如果是 Docker 环境注意 IP 地址的映射问题。动态刷新不生效确保类上加了RefreshScope注解。确保引入了spring-boot-starter-actuator依赖。通过以上步骤你已经成功将 Nacos 集成到了 Spring Boot 3.x 项目中实现了微服务架构中最核心的注册与配置功能。