维护微服务的人迟早会撞上一个问题改一条配置到底能不能不重启Nacos 还没普及的年代答案基本是“不能”改个超时、改个阈值都要走发布流程。现在大家默认 Nacos 配置中心就该支持动态刷新可真出了“配置变了没生效”的工单能讲清楚动态刷新背后链路的人其实没几个。我见过太多同行把 Nacos 动态刷新和 RefreshScope 当成同一个东西实际它俩分工完全不同Nacos 负责告诉你的应用“配置有变化”而 RefreshScope 负责把 Spring 容器里的旧 Bean 销毁再重建。缺了任何一环热更新都走不通。这篇就把两条原理链路完整拆一遍顺便复盘我在生产环境追查配置不生效时踩过的坑。1. 先定位配置热更新到底是谁的职责Nacos管一段Spring管一段很多排错困难都是从“职责混淆”开始的。Nacos 动态刷新和 RefreshScope 并不是并列的两种热更新方案而是不同层级的组件。Nacos 在配置层面负责“感知变化并通知”Spring 在 Bean 生命周期层面负责“让新配置进入业务代码”。搞清楚这条链路上有哪些角色后面看源码才不会迷路。1.1 一次配置变更的宏观链路先给整条链路画个全景图后面每一节再展开环节负责方产出配置写入Nacos Server新版本的配置内容客户端感知Nacos Client长轮询发现 dataId 的 MD5 变化事件发布Spring Cloud Alibaba触发 RefreshEvent环境更新Spring Cloud ContextEnvironment 中的 PropertySource 被替换为新值Bean 重建RefreshScope旧 Bean 销毁、新 Bean 懒加载创建业务读取业务代码通过代理拿到新 Bean、新值你可以把这条链想象成餐厅换菜单Nacos 服务端是后厨改了菜单后通知传菜员Nacos Client 是传菜员他一直在窗口等着“菜单有没有变”Spring Cloud Alibaba 是传菜员的呼叫器一收到变化就喊一声“换菜单了”RefreshScope 是服务员他负责把顾客手里那份旧菜单收走换成新菜单。顾客下次点菜自然用的就是新菜单。这个类比里有一个关键点菜单不是被“修改”的而是被“换掉”的。Spring 里配置动态刷新的本质也不是在内存里把某个字段的值从 3 改成 5而是把这个字段所在的 Bean 整个销毁再重新创建一个。很多人不理解这一点才会在排查时怎么都想不通。1.2 每个环节的边界在哪里Nacos 本身不关心你的 Bean 是否刷新。它只做一件事客户端订阅了某个 dataId当这个 dataId 的内容变化时保证客户端能在一定时间内收到通知。至于收到通知之后是打日志、发邮件还是触发 Spring 的 RefreshEvent这不在 Nacos 的职责内。RefreshScope 本身也完全不感知 Nacos。它只是 Spring Cloud Context 提供的一个自定义作用域标注了这个注解的 Bean 具备“被外部指令销毁重建”的能力。触发它的指令可以是 Nacos 的动态刷新也可以是 Spring Cloud Config Server 的刷新甚至可以是你自己手动调用ContextRefresher.refresh()。这个边界划分很重要。排查“配置没刷新”时先判断问题是出在 Nacos 到 Environment 这一段还是出在 Environment 到 Bean 这一段。我见过太多人花一天时间查 Nacos 配置、查网络最后发现是 Bean 上没加 RefreshScope或者加的位置不对。1.3 官方文档不会明说的分工细节Spring Cloud Alibaba 的 Nacos Config 模块本质上是一个“监听器搬运工”。它把 Nacos 客户端的配置变更监听器转译为 Spring Cloud 的 RefreshEvent。而 Spring Cloud Context 里的RefreshEventListener收到事件后调用ContextRefresher.refresh()。这个refresh()方法才是真正干活的更新 Environment刷新 RefreshScope。所以你去翻源码会发现关键类就几个NacosContextRefresher、RefreshEvent、RefreshEventListener、ContextRefresher、RefreshScope。你把这几个类的调用关系理清整个动态刷新原理就拿下了一半。2. Nacos客户端的长轮询刷新“第一公里”怎么跑Nacos 动态刷新的第一公里是客户端如何知道服务端配置变了。早期 Nacos 1.x 的核心机制叫“长轮询”这个机制至今仍是理解 Nacos 推送模型最好的切入口。2.x 之后虽然默认走 gRPC 双向流但核心的“MD5 对比 变更通知 客户端拉取”思路一脉相承。2.1 为什么是长轮询而不是短轮询或 WebSocket短轮询最傻客户端每隔几秒发起一次 HTTP 请求问“配置变了吗”。大部分请求都是白问服务端压力大实时性还受轮询间隔限制。WebSocket 可以把实时性拉到毫秒级但需要维护长连接、心跳、断线重连服务端还要维护每个客户端的订阅状态复杂度高很多。Nacos 作为一个中间件要同时服务成千上万个客户端用长轮询是性价比很高的选择。长轮询的精髓是客户端发起一次 HTTP 请求服务端收到后先不响应把这个请求“挂住”。挂住期间如果有配置变更服务端立刻响应如果没有等超时时间快到了再响应一个空结果。客户端收到空结果后立即发起下一次请求。这样既不浪费频繁请求又能做到秒级感知。我常用一个食堂窗口的类比短轮询是每 5 秒跑过去问一次“菜好了吗”长轮询是过去问一次“菜好了吗”没好就站在窗口等好了直接端走。服务员不会把你晾在那不管最迟 30 秒也会告诉你“还没好再等等”。2.2 长轮询的完整工作链路Nacos 客户端的核心类是ClientWorker。它维护了一个缓存结构每个订阅的 dataId 对应一个CacheData里面记录了配置内容和 MD5 值。整个长轮询流程大致如下ClientWorker启动一个长轮询线程把当前所有订阅配置的 dataId、group、MD5 拼成一个参数列表发给 Nacos 服务端的配置监听接口。服务端接到请求后把请求挂起来最长持有约 29.5 秒。在这期间如果有人修改了某个配置服务端立刻对比该 dataId 的 MD5。不一致就说明变了服务端立即返回“这几个 dataId 有变化”。如果 29.5 秒内没有任何变化服务端返回一个空列表客户端收到空列表后马上发起下一次长轮询。客户端拿到有变化的 dataId 列表后逐个调用配置查询接口拉取最新配置内容更新本地CacheData并触发这个 dataId 上注册的所有监听器。这里有个关键细节判断“配置是否变化”靠的是 MD5 对比。客户端在长轮询请求里带上自己缓存内容的 MD5服务端拿当前配置文件的 MD5 去比不一致就认为有变化。所以哪怕你只是修改了配置文件里的一个空格MD5 也会变也会触发一次完整刷新链路。2.3 30秒的窗口是怎么来的客户端发起长轮询时会在请求里带上一个超时时间默认是 30 秒。服务端收到后会调度一个延迟任务在 29.5 秒左右时检查一遍所有关注的配置。如果没变化就返回空结果如果有变化就提前返回。这个设计保证了最差情况下客户端也能在约 30 秒内感知到配置变更。实际情况里由于服务端是“有变化立即返回”所以你在 Nacos 控制台改完配置后客户端通常一两秒内就能收到通知极端情况下最多等一个轮询周期。2.x 之后Nacos 默认用 gRPC 双向流做配置推送客户端和服务端建立一条常驻连接服务端有变更时直接通过这条流推过去。但它并没有完全抛弃 MD5 对比的思路配置内容的最终生效仍然要经过客户端重新拉取、更新本地缓存、触发监听器这一套流程。所以我一直觉得把 1.x 的长轮询吃透你对 Nacos 动态刷新原理的理解就算入门了。2.4 长轮询里隐藏的线程模型问题ClientWorker内部有两个线程池一个负责调度长轮询任务一个负责处理配置变更后的拉取和监听器回调。这里藏着一个很容易踩的坑如果你的配置变更监听器里做了耗时操作比如查数据库、调外部接口它会阻塞CacheData的监听器回调线程后续其他配置的变更通知也会跟着排队。我见过有人把数据同步逻辑直接写进 Nacos 的Listener.receiveConfigInfo里配置一变更同步耗时 5 秒中间又改了另一条配置结果所有 listener 都堵在一起。正确做法是监听器里只做轻量级处理耗时逻辑丢到独立的业务线程池里异步执行。3. RefreshScope的真面目不是改值是销毁重建说完了 Nacos 这一段再看 Spring 这一段。RefreshScope 是理解“配置热更新为什么有的字段生效、有的字段死活不生效”的关键。3.1 从 Bean 作用域说起Spring 里常规的 Bean 作用域有singleton和prototype单例就是容器里只存一份每次获取都是同一个实例原型是每次获取都新建一个。RefreshScope 其实是在 Spring Cloud 里注册了一个自定义作用域名字叫refresh。被它标注的 Bean不再是纯粹的 singleton而是处于一个可以被整体清空的“刷新作用域”里。我第一次看源码时有个疑问既然不是 singleton那每次注入 RefreshScope Bean 是不是都会新建对象并不是。RefreshScope 内部维护了一个缓存同一个 Bean 在缓存里还是单例的只是这个缓存可以被外部指令一次性清空。清空之后下次再有人获取这个 Bean才会重新走一遍完整的 Bean 创建流程。3.2 代理刷新机制的入口RefreshScope 原理里最关键的设计是代理。当一个类标注了 RefreshScopeSpring 在注册这个 Bean 时会通过ScopedProxyUtils给它生成一个代理对象。业务代码里注入的其实是这个代理而不是真实 Bean。为什么非要代理因为真实 Bean 可能随时被销毁重建但业务代码里注入的引用不能变来变去。代理像一个稳定的前台接待员你每次找它办业务它都去后面找“现在负责这件事的人”。如果后面的责任人换了前台不用变你下次来自然面对新人。所以RefreshScope 的核心并不是“刷新时更新已经注入的实例”而是“刷新时把缓存里的实例丢掉代理仍然存在下次调用时自动触发重新创建”。3.3 refresh 到底做了什么RefreshScope继承自GenericScope内部维护了一个scopeCache用 Bean 名作为 key 存实例。当你要刷新时调用refreshAll()或refresh(name)它做的事情非常直白遍历scopeCache找到所有 refresh 作用域下的 Bean 实例。对每个实例执行销毁回调比如 PreDestroy 方法。从缓存里移除实例。完事。注意这里并没有立即创建新 Bean。清理缓存之后新 Bean 是“懒加载”的直到某个业务方法真正调用代理代理才会发现缓存里没有目标于是走一遍完整的 Bean 创建流程——实例化、属性注入、初始化回调全部重来。这个“销毁后懒重建”的特性后面会引出一堆生产环境问题。所以你可以把 RefreshScope 理解成换灯泡的动作不是用遥控器把旧灯泡调亮而是把旧灯泡拧下来扔掉等下一次需要光线时再拿一颗新灯泡拧上去。3.4 为什么 Value 能拿到新值既然 Bean 整个重建了Value 注入的属性自然是在新 Bean 实例化阶段重新解析的。Spring 解析 Value 时读的是Environment里的属性源。只要Environment中已经更新成了 Nacos 的新配置新 Bean 拿到的就是新值。这里有一个潜在误区有人以为 RefreshScope 是“把新配置值直接塞进旧对象里”。不是的。旧对象已经被销毁了你拿到的是一个全新对象。这也是为什么你会看到刷新之后某些初始化逻辑比如连接池建立、本地缓存加载会再次执行一遍。不是 Bug是机制本身如此。3.5 RefreshScope 的管理范围RefreshScope 只对 Spring 管理的 Bean 有效。你手动new出来的对象静态字段里存的对象或者已经脱离容器管理的实例都不受刷新影响。很多“刷新没生效”的工单最后查下来都是对象逃逸出了容器管理。举一个最常见的场景Component RefreshScope public class OrderProperties { Value(${order.timeout:3000}) private int timeout; public int getTimeout() { return timeout; } }单独看这个类是没问题的。问题往往出现在下面这种写法public class OrderService { Autowired private OrderProperties orderProperties; private static int cachedTimeout orderProperties.getTimeout(); public int getTimeout() { return cachedTimeout; } }cachedTimeout在 OrderService 实例化时被赋值一次之后就再也不会更新。哪怕 OrderProperties 被刷新成新对象这个 static 字段里存的还是旧值。这不是 RefreshScope 的锅是业务代码把动态的值提前快照了。4. 从Nacos变更到Bean重建一条事件链上的三次配合前两节把两段链路分别讲清楚了这一节把它们接起来看看一次 Nacos 配置变更到底是怎么一步步走到业务代码里的。4.1 Nacos 客户的监听器如何被触发关键类叫NacosContextRefresher。它会在应用启动后为每个订阅的 dataId 注册一个监听器到 Nacos 客户端。这个监听器实现的回调方法就是 Nacos 的Listener.receiveConfigInfo(String configInfo)。当第 2 节讲的长轮询或 gRPC 推送发现配置变更客户端更新本地缓存后就会调用这个回调方法把最新配置内容以字符串形式传进来。NacosContextRefresher拿到这段字符串后会先判断这个变更是否属于自己关心的配置然后发布一个RefreshEvent。这里有一个容易被忽略的性能点Nacos 客户端收到的configInfo是完整的配置文本不是增量。所以如果配置文件很大每次变更都会完整传一次。配置内容超过几十 KB 时建议拆分 dataId把动态变更频繁的配置独立出来避免每次刷新都把大配置来回传。4.2 RefreshEvent 与 ContextRefresherRefreshEvent是 Spring Cloud Context 里定义的一个普通 Spring 事件。RefreshEventListener监听它收到后调用ContextRefresher.refresh()。这才是动态刷新真正干活的地方。ContextRefresher.refresh()做了三件事顺序很有讲究更新Environment里的可刷新属性源把 Nacos 上的新配置值写进 Spring 的环境变量。调用RefreshScope.refresh()把 refresh 作用域下所有 Bean 的缓存清掉。发布EnvironmentChangeEvent告诉容器里其他组件“环境变了”。顺序必须是先更新 Environment再清 Bean 缓存。因为第二步清完缓存后新 Bean 不会立刻创建而是等下次调用时再创建创建时解析 Value 或绑定 ConfigurationProperties都要读 Environment。如果顺序反了新 Bean 创建时读到还是旧 Environment等于白刷新。4.3 为什么 ConfigurationProperties 不一定要 RefreshScope有个现象你可能见过某个配置类没有加 RefreshScope但 Nacos 刷新后它也能拿到新值。这是因为ContextRefresher.refresh()除了清理 RefreshScope还会触发ConfigurationPropertiesRebinder重新绑定所有 ConfigurationProperties Bean。不过我不建议你依赖这个特性。两类情况很容易翻车配置类里同时混用了 Value 和 ConfigurationPropertiesrebind 只处理属性绑定不重新解析 Value。配置类被手动 new 过或者被多个上下文共享rebind 可能找不到它。稳定的做法是凡是需要动态刷新的配置类统一加 RefreshScope。它走的是“销毁重建 Bean”这条路任何类型的注入逻辑都会重新走一遍最稳。4.4 Environment 更新这一步的隐藏风险ContextRefresher.refresh()更新 Environment 时不是简单把新字符串塞进去而是要替换或新增对应的 PropertySource。如果你在 Nacos 里改动了配置格式比如 local 配置是 properties线上配置是 yaml解析器不一样很可能导致整个配置源加载失败。我自己就踩过dataId 后缀是 yaml但控制台编辑时误选了 properties 格式保存后客户端拉取内容时解析报错业务代码里的配置值全部变成 null接口大面积报错。这种问题日志里往往只有一行 “load config error”不仔细看很容易漏。所以我的建议是dataId 的扩展名、Nacos 控制台里选择的格式、Spring Boot 配置的 file-extension 这三处必须保持一致。4.5 新版本配置加载方式带来的差异Spring Cloud Alibaba 早期版本需要依赖 bootstrapNacos 配置源会在业务应用启动的很早期就挂进 Environment。新版本推荐使用spring.config.import方式配置加载时序和 bootstrap 模式略有不同但动态刷新的事件链是同一个Nacos 客户端感知变更发布 RefreshEventContextRefresher 处理。如果你用的是新版本留意一下spring.config.import里声明的 dataId 顺序。多个 dataId 同时存在时谁在前面谁优先级高。同一把 key 在多个 dataId 里出现刷新后到底读到哪一个取决于 PropertySource 在 Environment 里的排列位置。最好的规避方式是不要在不同 dataId 里配重复的 key省得给自己埋雷。5. 生产现场复盘的四个“刷新失败”案例原理讲得再透不如真实案例有说服力。下面四个案例都是我在生产环境遇到过或者帮同事排查过的每个都对应一种典型病因。5.1 现场A日志显示刷新了业务值就是没变现象Nacos 控制台改了配置客户端日志能看到 “data-received”Environment 里的值也是新的但业务接口返回的还是旧值。排查发现业务代码里根本没有依赖 Spring 注入的 Bean而是把一个配置值存在了 static 字段里其他类直接读这个 static 字段。RefreshScope 重建的 Bean 是新的但 static 字段还留在老地方值不变。这种问题最迷惑人的地方在于你要刷新整个类不仅需要加 RefreshScope还需要保证所有调用方都是通过 Spring 容器拿到的代理对象。凡是绕过容器的访问路径都能让刷新“看起来没生效”。修复方式是把 static 缓存改成实例字段或者每次使用时从 Spring 容器获取代理。5.2 现场B异步线程池里的任务拿着旧配置现象一个 Async 异步任务里读取配置值Nacos 刷新后主线程里拿到的是新值异步线程里拿到的永远是旧值。原因通常是任务提交时就把配置值从 Bean 里读出来放进了任务对象线程池执行时用的已经是快照。这类问题和 RefreshScope 无关是“配置值被过早快照”导致的。但有一种情况确实和 RefreshScope 有关如果异步线程池里的 Bean 是一个普通单例并且在初始化阶段就缓存了配置对象的引用刷新后这个单例仍然持有旧引用。解决方法是让异步处理的 Bean 直接注入 RefreshScope 代理对象每次调用 getter 都走代理拿到最新值。关键判断标准是代码里用的是配置 Bean 的 getter还是提前取出来存好的变量。5.3 现场C刷新导致数据源连接池反复重建现象把数据源相关配置类加了 RefreshScope一改动配置连接池被销毁重建线上瞬间出现大量数据库连接超时。这就是我前面说的“销毁后懒重建”的副作用。连接池这类重量级资源销毁时正在执行的请求会被打断重建时又要经历完整初始化。多个线程同时访问代理还可能并发触发多次初始化竞争。我后来定的规矩是数据源、Redis、MQ 连接工厂这类重 Bean一律不允许加 RefreshScope。涉及这类组件的配置变更走发布流程重启。真正动态刷新的只放线程池参数、超时阈值、业务开关、降级比例这类轻量级配置。5.4 现场DNacos 里改了配置客户端压根没订阅现象Nacos 控制台配置改得很顺利客户端日志里一点动静都没有。这类问题多半是 dataId 对不上。Nacos 配置中心的 dataId 默认拼接规则是${spring.application.name}-${profile}.${file-extension}如果应用没配spring.application.name或者 Nacos 里建的数据 Id 和这个规则不一致客户端根本不会订阅这个配置。还有个容易被忽略的点file-extension默认是 properties。如果你在 Nacos 里存的是 yaml 文件应用里的spring.cloud.nacos.config.file-extension也要配成 yaml。两边格式不一致时客户端会订阅但解析阶段会出问题效果和没订阅差不多。5.5 一套完整的排查链路遇到配置不刷新我建议按下面的顺序定位每一步都有明确结论确认 Nacos 服务端配置真的保存成功了看一下配置历史的版本号有没有变化。看客户端日志有没有>RestController RefreshScope public class OrderConfigController { private final OrderProperties orderProperties; public OrderConfigController(OrderProperties orderProperties) { this.orderProperties orderProperties; } GetMapping(/debug/order-config) public String debug() { return hash System.identityHashCode(orderProperties) , timeout orderProperties.getTimeout(); } }这个方法比看日志直观太多。很多“刷新到底成没成功”的争论一个接口就能证明。6.3 配置改错之后的快速回滚Nacos 配置中心自带历史版本功能每次变更都会留下版本记录。如果改完配置发现线上异常不要急着手动改回去直接在历史版本里选择上一个版本一键回滚。回滚动作本身也是一次配置变更会重新触发整条刷新链路比手动编辑再保存更少人工错误。最后说一个真实感受把 Nacos 动态刷新和 RefreshScope 这两条链路彻底理清之后再遇到配置不生效的工单我基本能在一分钟内判断出问题出在哪一段。大多数疑难杂症本质上都不是 Nacos 或 Spring Cloud 的 Bug而是对“谁负责通知、谁负责重建、谁在什么时候读什么值”这三个问题没想清楚。搞懂这套机制比背一百个配置项有用得多。
维护微服务的人迟早会撞上一个问题改一条配置到底能不能不重启Nacos 还没普及的年代答案基本是“不能”改个超时、改个阈值都要走发布流程。现在大家默认 Nacos 配置中心就该支持动态刷新可真出了“配置变了没生效”的工单能讲清楚动态刷新背后链路的人其实没几个。我见过太多同行把 Nacos 动态刷新和 RefreshScope 当成同一个东西实际它俩分工完全不同Nacos 负责告诉你的应用“配置有变化”而 RefreshScope 负责把 Spring 容器里的旧 Bean 销毁再重建。缺了任何一环热更新都走不通。这篇就把两条原理链路完整拆一遍顺便复盘我在生产环境追查配置不生效时踩过的坑。1. 先定位配置热更新到底是谁的职责Nacos管一段Spring管一段很多排错困难都是从“职责混淆”开始的。Nacos 动态刷新和 RefreshScope 并不是并列的两种热更新方案而是不同层级的组件。Nacos 在配置层面负责“感知变化并通知”Spring 在 Bean 生命周期层面负责“让新配置进入业务代码”。搞清楚这条链路上有哪些角色后面看源码才不会迷路。1.1 一次配置变更的宏观链路先给整条链路画个全景图后面每一节再展开环节负责方产出配置写入Nacos Server新版本的配置内容客户端感知Nacos Client长轮询发现 dataId 的 MD5 变化事件发布Spring Cloud Alibaba触发 RefreshEvent环境更新Spring Cloud ContextEnvironment 中的 PropertySource 被替换为新值Bean 重建RefreshScope旧 Bean 销毁、新 Bean 懒加载创建业务读取业务代码通过代理拿到新 Bean、新值你可以把这条链想象成餐厅换菜单Nacos 服务端是后厨改了菜单后通知传菜员Nacos Client 是传菜员他一直在窗口等着“菜单有没有变”Spring Cloud Alibaba 是传菜员的呼叫器一收到变化就喊一声“换菜单了”RefreshScope 是服务员他负责把顾客手里那份旧菜单收走换成新菜单。顾客下次点菜自然用的就是新菜单。这个类比里有一个关键点菜单不是被“修改”的而是被“换掉”的。Spring 里配置动态刷新的本质也不是在内存里把某个字段的值从 3 改成 5而是把这个字段所在的 Bean 整个销毁再重新创建一个。很多人不理解这一点才会在排查时怎么都想不通。1.2 每个环节的边界在哪里Nacos 本身不关心你的 Bean 是否刷新。它只做一件事客户端订阅了某个 dataId当这个 dataId 的内容变化时保证客户端能在一定时间内收到通知。至于收到通知之后是打日志、发邮件还是触发 Spring 的 RefreshEvent这不在 Nacos 的职责内。RefreshScope 本身也完全不感知 Nacos。它只是 Spring Cloud Context 提供的一个自定义作用域标注了这个注解的 Bean 具备“被外部指令销毁重建”的能力。触发它的指令可以是 Nacos 的动态刷新也可以是 Spring Cloud Config Server 的刷新甚至可以是你自己手动调用ContextRefresher.refresh()。这个边界划分很重要。排查“配置没刷新”时先判断问题是出在 Nacos 到 Environment 这一段还是出在 Environment 到 Bean 这一段。我见过太多人花一天时间查 Nacos 配置、查网络最后发现是 Bean 上没加 RefreshScope或者加的位置不对。1.3 官方文档不会明说的分工细节Spring Cloud Alibaba 的 Nacos Config 模块本质上是一个“监听器搬运工”。它把 Nacos 客户端的配置变更监听器转译为 Spring Cloud 的 RefreshEvent。而 Spring Cloud Context 里的RefreshEventListener收到事件后调用ContextRefresher.refresh()。这个refresh()方法才是真正干活的更新 Environment刷新 RefreshScope。所以你去翻源码会发现关键类就几个NacosContextRefresher、RefreshEvent、RefreshEventListener、ContextRefresher、RefreshScope。你把这几个类的调用关系理清整个动态刷新原理就拿下了一半。2. Nacos客户端的长轮询刷新“第一公里”怎么跑Nacos 动态刷新的第一公里是客户端如何知道服务端配置变了。早期 Nacos 1.x 的核心机制叫“长轮询”这个机制至今仍是理解 Nacos 推送模型最好的切入口。2.x 之后虽然默认走 gRPC 双向流但核心的“MD5 对比 变更通知 客户端拉取”思路一脉相承。2.1 为什么是长轮询而不是短轮询或 WebSocket短轮询最傻客户端每隔几秒发起一次 HTTP 请求问“配置变了吗”。大部分请求都是白问服务端压力大实时性还受轮询间隔限制。WebSocket 可以把实时性拉到毫秒级但需要维护长连接、心跳、断线重连服务端还要维护每个客户端的订阅状态复杂度高很多。Nacos 作为一个中间件要同时服务成千上万个客户端用长轮询是性价比很高的选择。长轮询的精髓是客户端发起一次 HTTP 请求服务端收到后先不响应把这个请求“挂住”。挂住期间如果有配置变更服务端立刻响应如果没有等超时时间快到了再响应一个空结果。客户端收到空结果后立即发起下一次请求。这样既不浪费频繁请求又能做到秒级感知。我常用一个食堂窗口的类比短轮询是每 5 秒跑过去问一次“菜好了吗”长轮询是过去问一次“菜好了吗”没好就站在窗口等好了直接端走。服务员不会把你晾在那不管最迟 30 秒也会告诉你“还没好再等等”。2.2 长轮询的完整工作链路Nacos 客户端的核心类是ClientWorker。它维护了一个缓存结构每个订阅的 dataId 对应一个CacheData里面记录了配置内容和 MD5 值。整个长轮询流程大致如下ClientWorker启动一个长轮询线程把当前所有订阅配置的 dataId、group、MD5 拼成一个参数列表发给 Nacos 服务端的配置监听接口。服务端接到请求后把请求挂起来最长持有约 29.5 秒。在这期间如果有人修改了某个配置服务端立刻对比该 dataId 的 MD5。不一致就说明变了服务端立即返回“这几个 dataId 有变化”。如果 29.5 秒内没有任何变化服务端返回一个空列表客户端收到空列表后马上发起下一次长轮询。客户端拿到有变化的 dataId 列表后逐个调用配置查询接口拉取最新配置内容更新本地CacheData并触发这个 dataId 上注册的所有监听器。这里有个关键细节判断“配置是否变化”靠的是 MD5 对比。客户端在长轮询请求里带上自己缓存内容的 MD5服务端拿当前配置文件的 MD5 去比不一致就认为有变化。所以哪怕你只是修改了配置文件里的一个空格MD5 也会变也会触发一次完整刷新链路。2.3 30秒的窗口是怎么来的客户端发起长轮询时会在请求里带上一个超时时间默认是 30 秒。服务端收到后会调度一个延迟任务在 29.5 秒左右时检查一遍所有关注的配置。如果没变化就返回空结果如果有变化就提前返回。这个设计保证了最差情况下客户端也能在约 30 秒内感知到配置变更。实际情况里由于服务端是“有变化立即返回”所以你在 Nacos 控制台改完配置后客户端通常一两秒内就能收到通知极端情况下最多等一个轮询周期。2.x 之后Nacos 默认用 gRPC 双向流做配置推送客户端和服务端建立一条常驻连接服务端有变更时直接通过这条流推过去。但它并没有完全抛弃 MD5 对比的思路配置内容的最终生效仍然要经过客户端重新拉取、更新本地缓存、触发监听器这一套流程。所以我一直觉得把 1.x 的长轮询吃透你对 Nacos 动态刷新原理的理解就算入门了。2.4 长轮询里隐藏的线程模型问题ClientWorker内部有两个线程池一个负责调度长轮询任务一个负责处理配置变更后的拉取和监听器回调。这里藏着一个很容易踩的坑如果你的配置变更监听器里做了耗时操作比如查数据库、调外部接口它会阻塞CacheData的监听器回调线程后续其他配置的变更通知也会跟着排队。我见过有人把数据同步逻辑直接写进 Nacos 的Listener.receiveConfigInfo里配置一变更同步耗时 5 秒中间又改了另一条配置结果所有 listener 都堵在一起。正确做法是监听器里只做轻量级处理耗时逻辑丢到独立的业务线程池里异步执行。3. RefreshScope的真面目不是改值是销毁重建说完了 Nacos 这一段再看 Spring 这一段。RefreshScope 是理解“配置热更新为什么有的字段生效、有的字段死活不生效”的关键。3.1 从 Bean 作用域说起Spring 里常规的 Bean 作用域有singleton和prototype单例就是容器里只存一份每次获取都是同一个实例原型是每次获取都新建一个。RefreshScope 其实是在 Spring Cloud 里注册了一个自定义作用域名字叫refresh。被它标注的 Bean不再是纯粹的 singleton而是处于一个可以被整体清空的“刷新作用域”里。我第一次看源码时有个疑问既然不是 singleton那每次注入 RefreshScope Bean 是不是都会新建对象并不是。RefreshScope 内部维护了一个缓存同一个 Bean 在缓存里还是单例的只是这个缓存可以被外部指令一次性清空。清空之后下次再有人获取这个 Bean才会重新走一遍完整的 Bean 创建流程。3.2 代理刷新机制的入口RefreshScope 原理里最关键的设计是代理。当一个类标注了 RefreshScopeSpring 在注册这个 Bean 时会通过ScopedProxyUtils给它生成一个代理对象。业务代码里注入的其实是这个代理而不是真实 Bean。为什么非要代理因为真实 Bean 可能随时被销毁重建但业务代码里注入的引用不能变来变去。代理像一个稳定的前台接待员你每次找它办业务它都去后面找“现在负责这件事的人”。如果后面的责任人换了前台不用变你下次来自然面对新人。所以RefreshScope 的核心并不是“刷新时更新已经注入的实例”而是“刷新时把缓存里的实例丢掉代理仍然存在下次调用时自动触发重新创建”。3.3 refresh 到底做了什么RefreshScope继承自GenericScope内部维护了一个scopeCache用 Bean 名作为 key 存实例。当你要刷新时调用refreshAll()或refresh(name)它做的事情非常直白遍历scopeCache找到所有 refresh 作用域下的 Bean 实例。对每个实例执行销毁回调比如 PreDestroy 方法。从缓存里移除实例。完事。注意这里并没有立即创建新 Bean。清理缓存之后新 Bean 是“懒加载”的直到某个业务方法真正调用代理代理才会发现缓存里没有目标于是走一遍完整的 Bean 创建流程——实例化、属性注入、初始化回调全部重来。这个“销毁后懒重建”的特性后面会引出一堆生产环境问题。所以你可以把 RefreshScope 理解成换灯泡的动作不是用遥控器把旧灯泡调亮而是把旧灯泡拧下来扔掉等下一次需要光线时再拿一颗新灯泡拧上去。3.4 为什么 Value 能拿到新值既然 Bean 整个重建了Value 注入的属性自然是在新 Bean 实例化阶段重新解析的。Spring 解析 Value 时读的是Environment里的属性源。只要Environment中已经更新成了 Nacos 的新配置新 Bean 拿到的就是新值。这里有一个潜在误区有人以为 RefreshScope 是“把新配置值直接塞进旧对象里”。不是的。旧对象已经被销毁了你拿到的是一个全新对象。这也是为什么你会看到刷新之后某些初始化逻辑比如连接池建立、本地缓存加载会再次执行一遍。不是 Bug是机制本身如此。3.5 RefreshScope 的管理范围RefreshScope 只对 Spring 管理的 Bean 有效。你手动new出来的对象静态字段里存的对象或者已经脱离容器管理的实例都不受刷新影响。很多“刷新没生效”的工单最后查下来都是对象逃逸出了容器管理。举一个最常见的场景Component RefreshScope public class OrderProperties { Value(${order.timeout:3000}) private int timeout; public int getTimeout() { return timeout; } }单独看这个类是没问题的。问题往往出现在下面这种写法public class OrderService { Autowired private OrderProperties orderProperties; private static int cachedTimeout orderProperties.getTimeout(); public int getTimeout() { return cachedTimeout; } }cachedTimeout在 OrderService 实例化时被赋值一次之后就再也不会更新。哪怕 OrderProperties 被刷新成新对象这个 static 字段里存的还是旧值。这不是 RefreshScope 的锅是业务代码把动态的值提前快照了。4. 从Nacos变更到Bean重建一条事件链上的三次配合前两节把两段链路分别讲清楚了这一节把它们接起来看看一次 Nacos 配置变更到底是怎么一步步走到业务代码里的。4.1 Nacos 客户的监听器如何被触发关键类叫NacosContextRefresher。它会在应用启动后为每个订阅的 dataId 注册一个监听器到 Nacos 客户端。这个监听器实现的回调方法就是 Nacos 的Listener.receiveConfigInfo(String configInfo)。当第 2 节讲的长轮询或 gRPC 推送发现配置变更客户端更新本地缓存后就会调用这个回调方法把最新配置内容以字符串形式传进来。NacosContextRefresher拿到这段字符串后会先判断这个变更是否属于自己关心的配置然后发布一个RefreshEvent。这里有一个容易被忽略的性能点Nacos 客户端收到的configInfo是完整的配置文本不是增量。所以如果配置文件很大每次变更都会完整传一次。配置内容超过几十 KB 时建议拆分 dataId把动态变更频繁的配置独立出来避免每次刷新都把大配置来回传。4.2 RefreshEvent 与 ContextRefresherRefreshEvent是 Spring Cloud Context 里定义的一个普通 Spring 事件。RefreshEventListener监听它收到后调用ContextRefresher.refresh()。这才是动态刷新真正干活的地方。ContextRefresher.refresh()做了三件事顺序很有讲究更新Environment里的可刷新属性源把 Nacos 上的新配置值写进 Spring 的环境变量。调用RefreshScope.refresh()把 refresh 作用域下所有 Bean 的缓存清掉。发布EnvironmentChangeEvent告诉容器里其他组件“环境变了”。顺序必须是先更新 Environment再清 Bean 缓存。因为第二步清完缓存后新 Bean 不会立刻创建而是等下次调用时再创建创建时解析 Value 或绑定 ConfigurationProperties都要读 Environment。如果顺序反了新 Bean 创建时读到还是旧 Environment等于白刷新。4.3 为什么 ConfigurationProperties 不一定要 RefreshScope有个现象你可能见过某个配置类没有加 RefreshScope但 Nacos 刷新后它也能拿到新值。这是因为ContextRefresher.refresh()除了清理 RefreshScope还会触发ConfigurationPropertiesRebinder重新绑定所有 ConfigurationProperties Bean。不过我不建议你依赖这个特性。两类情况很容易翻车配置类里同时混用了 Value 和 ConfigurationPropertiesrebind 只处理属性绑定不重新解析 Value。配置类被手动 new 过或者被多个上下文共享rebind 可能找不到它。稳定的做法是凡是需要动态刷新的配置类统一加 RefreshScope。它走的是“销毁重建 Bean”这条路任何类型的注入逻辑都会重新走一遍最稳。4.4 Environment 更新这一步的隐藏风险ContextRefresher.refresh()更新 Environment 时不是简单把新字符串塞进去而是要替换或新增对应的 PropertySource。如果你在 Nacos 里改动了配置格式比如 local 配置是 properties线上配置是 yaml解析器不一样很可能导致整个配置源加载失败。我自己就踩过dataId 后缀是 yaml但控制台编辑时误选了 properties 格式保存后客户端拉取内容时解析报错业务代码里的配置值全部变成 null接口大面积报错。这种问题日志里往往只有一行 “load config error”不仔细看很容易漏。所以我的建议是dataId 的扩展名、Nacos 控制台里选择的格式、Spring Boot 配置的 file-extension 这三处必须保持一致。4.5 新版本配置加载方式带来的差异Spring Cloud Alibaba 早期版本需要依赖 bootstrapNacos 配置源会在业务应用启动的很早期就挂进 Environment。新版本推荐使用spring.config.import方式配置加载时序和 bootstrap 模式略有不同但动态刷新的事件链是同一个Nacos 客户端感知变更发布 RefreshEventContextRefresher 处理。如果你用的是新版本留意一下spring.config.import里声明的 dataId 顺序。多个 dataId 同时存在时谁在前面谁优先级高。同一把 key 在多个 dataId 里出现刷新后到底读到哪一个取决于 PropertySource 在 Environment 里的排列位置。最好的规避方式是不要在不同 dataId 里配重复的 key省得给自己埋雷。5. 生产现场复盘的四个“刷新失败”案例原理讲得再透不如真实案例有说服力。下面四个案例都是我在生产环境遇到过或者帮同事排查过的每个都对应一种典型病因。5.1 现场A日志显示刷新了业务值就是没变现象Nacos 控制台改了配置客户端日志能看到 “data-received”Environment 里的值也是新的但业务接口返回的还是旧值。排查发现业务代码里根本没有依赖 Spring 注入的 Bean而是把一个配置值存在了 static 字段里其他类直接读这个 static 字段。RefreshScope 重建的 Bean 是新的但 static 字段还留在老地方值不变。这种问题最迷惑人的地方在于你要刷新整个类不仅需要加 RefreshScope还需要保证所有调用方都是通过 Spring 容器拿到的代理对象。凡是绕过容器的访问路径都能让刷新“看起来没生效”。修复方式是把 static 缓存改成实例字段或者每次使用时从 Spring 容器获取代理。5.2 现场B异步线程池里的任务拿着旧配置现象一个 Async 异步任务里读取配置值Nacos 刷新后主线程里拿到的是新值异步线程里拿到的永远是旧值。原因通常是任务提交时就把配置值从 Bean 里读出来放进了任务对象线程池执行时用的已经是快照。这类问题和 RefreshScope 无关是“配置值被过早快照”导致的。但有一种情况确实和 RefreshScope 有关如果异步线程池里的 Bean 是一个普通单例并且在初始化阶段就缓存了配置对象的引用刷新后这个单例仍然持有旧引用。解决方法是让异步处理的 Bean 直接注入 RefreshScope 代理对象每次调用 getter 都走代理拿到最新值。关键判断标准是代码里用的是配置 Bean 的 getter还是提前取出来存好的变量。5.3 现场C刷新导致数据源连接池反复重建现象把数据源相关配置类加了 RefreshScope一改动配置连接池被销毁重建线上瞬间出现大量数据库连接超时。这就是我前面说的“销毁后懒重建”的副作用。连接池这类重量级资源销毁时正在执行的请求会被打断重建时又要经历完整初始化。多个线程同时访问代理还可能并发触发多次初始化竞争。我后来定的规矩是数据源、Redis、MQ 连接工厂这类重 Bean一律不允许加 RefreshScope。涉及这类组件的配置变更走发布流程重启。真正动态刷新的只放线程池参数、超时阈值、业务开关、降级比例这类轻量级配置。5.4 现场DNacos 里改了配置客户端压根没订阅现象Nacos 控制台配置改得很顺利客户端日志里一点动静都没有。这类问题多半是 dataId 对不上。Nacos 配置中心的 dataId 默认拼接规则是${spring.application.name}-${profile}.${file-extension}如果应用没配spring.application.name或者 Nacos 里建的数据 Id 和这个规则不一致客户端根本不会订阅这个配置。还有个容易被忽略的点file-extension默认是 properties。如果你在 Nacos 里存的是 yaml 文件应用里的spring.cloud.nacos.config.file-extension也要配成 yaml。两边格式不一致时客户端会订阅但解析阶段会出问题效果和没订阅差不多。5.5 一套完整的排查链路遇到配置不刷新我建议按下面的顺序定位每一步都有明确结论确认 Nacos 服务端配置真的保存成功了看一下配置历史的版本号有没有变化。看客户端日志有没有>RestController RefreshScope public class OrderConfigController { private final OrderProperties orderProperties; public OrderConfigController(OrderProperties orderProperties) { this.orderProperties orderProperties; } GetMapping(/debug/order-config) public String debug() { return hash System.identityHashCode(orderProperties) , timeout orderProperties.getTimeout(); } }这个方法比看日志直观太多。很多“刷新到底成没成功”的争论一个接口就能证明。6.3 配置改错之后的快速回滚Nacos 配置中心自带历史版本功能每次变更都会留下版本记录。如果改完配置发现线上异常不要急着手动改回去直接在历史版本里选择上一个版本一键回滚。回滚动作本身也是一次配置变更会重新触发整条刷新链路比手动编辑再保存更少人工错误。最后说一个真实感受把 Nacos 动态刷新和 RefreshScope 这两条链路彻底理清之后再遇到配置不生效的工单我基本能在一分钟内判断出问题出在哪一段。大多数疑难杂症本质上都不是 Nacos 或 Spring Cloud 的 Bug而是对“谁负责通知、谁负责重建、谁在什么时候读什么值”这三个问题没想清楚。搞懂这套机制比背一百个配置项有用得多。
