《Spring Boot 4 与 Nacos 3.2.3 最强整合实战：配置管理 + 服务发现全解析》

Spring Boot 4.x 已全面拥抱 Jakarta EE 10底层基于 Spring Framework 6.x最低要求 JDK 17。Nacos 3.2.3 作为阿里云开源的最新稳定版不仅支持 gRPC 长连接还大幅提升了 AP 集群的可用性。两者结合堪称Java 微服务领域的新一代“黄金搭档”。适用场景微服务架构、云原生配置中心、服务注册与发现硬性要求JDK 17、Nacos 3.0.0、Spring Boot 4.1.0本文将从零开始手把手带你完成说明:笔者这里只是Demo Nacos 部署的单机版Nacos 3.2.3 单机Spring Boot 4.1.0 项目初始化配置中心动态刷新RefreshScope服务注册与发现Feign 客户端调用常见坑及解决方案环境准备踩坑预警组件版本备注JDK17推荐 21 LTS必须使用--enable-preview笔者JDK 安装的 JDK 25Spring Boot4.1.0当前最新 M2需使用 Spring Initializr 或手动调整 parentNacos Server3.2.3从 GitHub Release 下载Maven3.9笔者使用的 3.9.16Nacos 3.2.3 快速启动单机版Nacos 3.2.3 官网配置说明笔者提醒: Nacos 3.2.3 版本部署后共有三个端口。1.nacos.server.main.port8848原生核心端口含义这是 Nacos最核心的主端口也是兼容 2.x 时代的“万能入口”。作用处理HTTP 协议的请求。包括控制台的 API 调用、Spring Boot 应用通过application.yml拉取配置Config、服务实例的心跳上报HTTP 模式、以及 Admin 管理接口。注意虽然 3.x 默认建议用 gRPC但8848依然是所有客户端必须能访问的入口端口因为客户端初始化时首先会连接它进行握手和地址拉取。2.9848gRPC 长连接核心端口含义这是gRPC 协议的服务端监听端口。它不是让你在配置文件里手写的而是由8848自动偏移计算得出的计算规则main.port 1000即 8848 1000 9848。作用服务注册与发现核心Spring Boot 4.x 应用注册到 Nacos 时心跳维持、服务实例列表的实时推送Push全部走的是这个 9848 端口。配置长轮询配置中心的动态刷新监听Long Polling也复用该 gRPC 连接。致命坑点必看如果你的 Spring Boot 应用部署在容器或 K8s 中必须在安全组/防火墙中同时开放8848和9848。如果只开8848不开9848你的服务可以启动能拉取一次配置但几秒后就会报错断开连接且无法收到配置变更推送3.nacos.console.port8080独立控制台 Web 端口——3.x 新增含义这是 Nacos 3.x将前端界面Console UI与后端 API 剥离后的独立端口。作用专用于提供 Nacos 可视化控制台的网页资源HTML/CSS/JS和登录页面。为什么拆分为了让运维人员可以只将8080暴露给公网用于 UI 访问而将8848和9848封闭在内网提高 API 安全性。访问地址现在变成了http://你的IP:8080/nacos注意不再是 8848。注意如果该端口被占用启动会报错你可以通过-Dnacos.console.port8081修改。4.nacos.ai.registry.port9080AI 模型注册专用端口——3.x 重磅新特性含义这是 Nacos 3.2.3 专门为AI 原生场景开辟的独立 HTTP 端口。作用专用于AI 智能体Agent和大模型LLM的注册与发现。它走的是独立的语义化注册流程支持向量检索和元数据模糊匹配与传统的 Java 微服务Spring Boot注册逻辑隔离。对你当前文章的影响如果你是标准的 Spring Boot 4.x 微服务并不需要用到这个端口你的应用也不会连它。它只服务于 Python 的 AI 客户端如 Nacos-SDK-Python 3.x。如果你在写微服务实战可以在文末提一句“AI 端口仅供模型注册不影响业务服务”显得你研究得很深。如果连接超时可以试试 开放 所有使用到的端口号startup.sh -m standalone⚠️ 特别提醒linux 如果已经安装了低版本JDK需要修改一下startup.sh 启动文件在启动文件中指定新安装的高版本JDK路径即可如上图。 windows 环境一样。启动部署成功后访问:创建 Spring Boot 4.1.0 项目1. 父项目pom文件?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version4.1.0/version relativePath/ /parent groupIdcom.work/groupId artifactIdsirius-workspace/artifactId version1.0/version packagingpom/packaging modules modulesirius-iaas/module modulesirius-common/module modulesirius-iaas/gateway/module /modules properties java.version25/java.version spring-cloud.version2025.1.2/spring-cloud.version spring-cloud-alibaba.version2025.1.0.0/spring-cloud-alibaba.version cloud-starter-bootstrap.version5.0.2/cloud-starter-bootstrap.version webmvc-ui.version3.0.3/webmvc-ui.version hutool.version5.8.21/hutool.version mysql.version8.4.0/mysql.version mybatis-plus.version3.5.17/mybatis-plus.version dynamic.version4.5.0/dynamic.version commons-lang3.version3.20.0/commons-lang3.version jjwt.version0.13.0/jjwt.version jasypt.version4.0.4/jasypt.version validation.version4.1.0/validation.version /properties dependencies dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /dependency /dependencies !-- 依赖管理 先指定版本 后面就不需要指定版本了-- dependencyManagement dependencies !-- 1. Spring Cloud 依赖 BOMBill of Materials 作用统一管理 Spring Cloud 生态下所有组件如 OpenFeign、LoadBalancer、Gateway的版本。 原理typepom scopeimport 会将此 POM 中的 dependencyManagement 导入当前工程 避免为每个微服务组件单独指定版本号确保版本兼容性。 -- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency !-- 2. Spring Cloud Alibaba 依赖 BOM 作用统一管理 Alibaba 系微服务组件版本包括 - Nacos服务注册/配置中心 - Sentinel流量熔断/限流 - Seata分布式事务 注意请确保 ${spring-cloud-alibaba.version} 与上方的 Spring Cloud 版本严格对应。 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version${spring-cloud-alibaba.version}/version typepom/type scopeimport/scope /dependency !-- 3. Spring Cloud Bootstrap 启动器 作用让 Spring Boot 应用重新支持读取 bootstrap.yml / bootstrap.properties 配置文件。 -- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-bootstrap/artifactId version${cloud-starter-bootstrap.version}/version /dependency !-- 4. Hutool 全量工具包 作用提供丰富的 Java 工具方法涵盖字符串处理、日期计算、加密解密、HTTP 客户端、Excel 导出、二维码生成等。比 Apache Commons 更简洁且无额外依赖。 -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version${hutool.version}/version /dependency !-- springfox-swagger2 生成 OpenAPI v2 (Swagger 2.0) 格式的 RESTful API 文档接口。-- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version${webmvc-ui.version}/version scopecompile/scope /dependency !--MySQL JDBC 驱动-- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version${mysql.version}/version scopecompile/scope /dependency !-- 动态数据源多数据源Starter -- dependency groupIdcom.baomidou/groupId artifactIddynamic-datasource-spring-boot-starter/artifactId version${dynamic.version}/version /dependency !-- mybatis-plus-boot-starter 自动配置 SqlSessionFactory、事务管理、分页插件等并提供通用 Mapper、条件构造器等增强功能。 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version${mybatis-plus.version}/version scopecompile/scope /dependency !--mybatis-plus-annotation -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-annotation/artifactId version${mybatis-plus.version}/version scopecompile/scope /dependency !-- commons-lang3-提供 Java 核心库的增强工具类 -- dependency groupIdorg.apache.commons/groupId artifactIdcommons-lang3/artifactId version${commons-lang3.version}/version /dependency !-- JWT 令牌支持 -- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version${jjwt.version}/version /dependency !-- JJWT 的默认实现模块提供 JWT 签名、加密等具体逻辑。 -- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version${jjwt.version}/version scoperuntime/scope /dependency !--将 Jackson 作为 JJWT 的 JSON 序列化/反序列化实现-- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version${jjwt.version}/version scoperuntime/scope /dependency !-- 对 Spring Boot 配置文件 中的敏感信息如数据库密码、密钥进行加密和解密只需在配置中使用 ENC(加密值) 格式自动在运行时解密。 -- dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version${jasypt.version}/version scopecompile/scope /dependency !-- spring-boot-starter-validation 对 Controller 入参、Service 层方法参数及实体类字段进行声明式校验。-- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId version${validation.version}/version scopecompile/scope /dependency /dependencies /dependencyManagement /project2. 子项目pom文件?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdcom.work/groupId artifactIdsirius-workspace/artifactId version1.0/version relativePath../../pom.xml/relativePath /parent artifactIdgateway/artifactId description系统网关/description dependencies !-- 引入Spring Boot核心 -- dependency groupIdcom.work/groupId artifactIdsirius-common/artifactId version1.0/version /dependency !-- gateway 网关-- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !--gateway网关负载均衡依赖-- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-loadbalancer/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-bootstrap/artifactId /dependency !--限流引入redis-- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis-reactive/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency !-- Jasypt -- dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project2. 配置文件bootstrap.yml必选#启用配置文件 spring: profiles: active: ${profile:dev}2. 1 配置文件bootstrap-dev.yml必选spring: application: name: gateway cloud: nacos: discovery: server-addr: ${NACOS_SERVER:127.0.0.1:19110} namespace: ${NAME_SPACE:mation} username: ENC(kk6UhLPBlBwrj0IEY/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP9q0sYMWODWky9) password: ENC(b7rpZxmlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTw) group: ${GROUP_ID:DEFAULT_GROUP_DEV} config: server-addr: ${NACOS_SERVER:127.0.0.1:19110} file-extension: yaml namespace: ${NAME_SPACE:mation} username: ENC(kk6UhLPBlBwrj0IEY/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP9q0sYMWODWky9) password: ENC(b7rpZxmlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTw) group: ${GROUP_ID:DEFAULT_GROUP_DEV} refresh-enabled: true enabled: true bootstrap: enabled: true # nacos:${spring.application.name}-dev.yaml?groupDEFAULT_GROUP_DEVnamespacemationserver-addr127.0.0.1:19110 加密原字符串 config: import: ENC(JHcmATdBICFlFOLK8R9hSKVu7RTFJp/JHcmATdBICFfw8027w6d3OSfE5fzbrpCz5iMoJ67mfj8xIzt8GHcyyTphTBICFfw8027ww/MrxMidlUDI4XrpA7KbVHDEWsq1qAceSGP) logging: level: com.alibaba.nacos.client.naming: WARN com.alibaba.nacos: WARN jasypt: encryptor: password: ${JASYPT_PASSWORD}注: nacos 3.2.3 配置方式已经换成了spring.config.import,但是上面那个spring.cloud.nacos.config 也不能删除启动会报错在启动参数中加入密码:3. 主启动类package com.work; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; import org.springframework.cloud.context.config.annotation.RefreshScope; /** * version 1.0 * Description: 网关启动类 * Author 天狼 * date 2026-07-17 14:32 */ SpringBootApplication EnableDiscoveryClient RefreshScope public class GatewayApplication { private static Log log LogFactory.getLog(GatewayApplication.class); public static void main(String[] args) { SpringApplication.run(GatewayApplication.class,args); log.info(网关启动成功); } }到此填坑完成,尽情玩刷吧对你如果有帮助请给我个赞!