nacos-client 拆开一看只有 6 个包但 ClientWorker 一个类就占了 1800 行客户端整体架构拆解你写了两行代码nacos-client 替你跑了 6 个线程你在项目里写 Nacos 客户端只需要两行NamingServicenamingServiceNamingFactory.createNamingService(properties);namingService.registerInstance(order-service,10.0.1.10,8080);这两行背后发生了什么nacos-client 在后台启动了至少 6 个线程一个心跳发送线程、一个配置拉取线程、一个 gRPC 连接管理线程、一个 UDP 推送接收线程、一个本地缓存更新线程、一个重连检测线程。你以为你写的是一个普通的 SDK 调用实际上你启动了一个后台常驻的小型服务。这篇文章把 nacos-client 从 Maven 依赖里拉出来拆开看它到底由哪些模块组成、模块之间怎么配合、你写的每一行 API 背后触发了什么。⚠️ 本文基于 nacos-client 2.3.02024年12月发布。1.x 客户端的架构和本文描述有显著差异1.x 使用 HTTP 长轮询而非 gRPC、没有 RpcClient 模块、ClientWorker 内部逻辑完全不同。nacos-client 模块拆解6 个包4 层职责nacos-client 的 Maven 坐标是com.alibaba.nacos:nacos-client。它的包结构只有 6 个com.alibaba.nacos.client ├── api/ # 对外 API 接口层NamingService、ConfigService ├── auth/ # 认证相关Token 管理、登录接口 ├── config/ # 配置管理核心实现ClientWorker、ConfigService 实现 ├── naming/ # 服务发现核心实现NamingService 实现、BeatReactor ├── utils/ # 工具类网络、日志、环境检测 └── address/ # 地址服务器endpoint 解析、集群地址管理这 6 个包按职责分成 4 层基础层通信层业务层接口层api/NamingService 接口ConfigService 接口naming/服务注册、发现、心跳config/配置获取、监听、缓存auth/Token 管理address/服务端地址解析utils/网络、日志、环境接口层定义你能做什么业务层决定怎么做通信层管怎么连基础层管公共能力。每一层只调用下一层不跨层。 前面在服务端架构里也画过类似的分层Nacos-Server 4 个模块拆出来的 5 层结构客户端配置体系SystemConfig ClientConfig Properties你传给 Nacos 客户端的参数分三层优先级从高到低第一层Properties代码传入PropertiespropertiesnewProperties();properties.put(PropertyKeyConst.SERVER_ADDR,127.0.0.1:8848);properties.put(PropertyKeyConst.NAMESPACE,prod);properties.put(PropertyKeyConst.USERNAME,nacos);properties.put(PropertyKeyConst.PASSWORD,your_password);NamingServicenamingServiceNamingFactory.createNamingService(properties);这是最灵活的方式。每个 NamingService / ConfigService 实例可以有不同的配置。第二层ClientConfigSDK 默认值publicclassClientConfig{// 心跳间隔默认 5 秒privatelongheartBeatInterval5000L;// 超时时间默认 3 秒privatelongclientTimeout3000L;// 故障转移切换时间默认 30 秒privatelongfailoverSwitchTime30000L;// 本地缓存目录privateStringcacheDirSystem.getProperty(user.home)/nacos/naming;}ClientConfig 是 SDK 内部的默认值。Properties 里没有传的字段会回退到这里。第三层SystemConfig系统属性覆盖# JVM 启动参数优先级最高-DserverAddr127.0.0.1:8848-DnamespaceprodSystemConfig 在 Nacos 客户端启动时从 JVM 参数里读取。它优先级最高——会覆盖 Properties 里设置的值。配置加载优先级SystemConfig (JVM -D 参数) ↓ 如果没有 ClientConfig (SDK 默认值) ↓ 被覆盖 Properties (代码传入)⚠️ 适用边界在 Spring Cloud Alibaba 项目里配置不是通过 Properties 传的而是通过bootstrap.yml自动装配。自动装配最终也是构造 Properties 对象所以这里的优先级规则对 Spring Cloud 项目同样适用。通信层核心ClientWorkerClientWorker 是 nacos-client 里代码量最大的类也是客户端和服务端交互的核心枢纽。不管你是用 NamingService 还是 ConfigService底层都经过 ClientWorker。ClientWorker 的职责职责做了什么连接管理创建和管理到 Nacos 服务端的连接gRPC 或 HTTP心跳维护定时发送心跳保活检测连接状态请求转发把上层的 registerInstance / getConfig 调用转成服务端请求故障切换服务端挂掉后自动切换到备用节点配置监听维护配置变更的长连接接收服务端推送ClientWorker 内部的线程模型通信对象ClientWorker 内部线程HeartBeatThread定时发送心跳ConfigPollingThread配置轮询/监听FailoverThread故障切换检测CacheUpdateThread本地缓存更新Nacos Server 节点 ANacos Server 节点 BNacos Server 节点 CClientWorker 是一对多结构一个 ClientWorker 实例同时连接多个服务端节点每个节点有独立的连接和心跳状态。在 Nacos 1.x 里ClientWorker 使用 HTTP 长轮询做配置监听。每 30 秒发一次 HTTP 请求服务端挂起这个请求直到配置有变更或超时。在 Nacos 2.x 里ClientWorker 换成了 gRPC 双向流。连接建立后持续保持服务端有配置变更直接通过 stream 推送。ClientWorker 里多了一个 RpcClient 对象来管理这个流。事件驱动的异步通知模型nacos-client 不是同步阻塞的 SDK。你注册的 Listener 不是被调用的而是被通知的。事件流从服务端变更到你的 ListenerListenerEventQueueClientWorkerNacos ServerListenerEventQueueClientWorkerNacos Server配置变更推送(gRPC stream)放入 EventQueue异步调用 onChanged()你的业务逻辑关键组件组件作用EventQueue事件缓冲队列防止推送风暴时直接调用 ListenerNotifyCenterNacos 内部的事件总线统一管理事件发布和订阅Listener你注册的回调接口在配置变更时触发为什么用事件驱动而不是直接回调如果配置推送直接调用 Listener当服务端一次推送 100 个配置变更时你的 Listener 会被连续调用 100 次阻塞通信线程。事件驱动模型在中间加了一个 EventQueue。推送过来后先入队由独立的消费线程逐个取出调用 Listener。这样即使短时间大量推送也不会阻塞通信线程。// Nacos 内部的事件发布NotifyCenter.publishEvent(newConfigChangeEvent(dataId,group,content));// 你的监听器configService.addListener(dataId,group,newListener(){OverridepublicExecutorgetExecutor(){// 返回 null 表示用默认线程池// 也可以返回自定义 Executorreturnnull;}OverridepublicvoidreceiveConfigInfo(StringconfigInfo){// 这里的 configInfo 是新的配置内容// 更新你的业务对象}});服务发现的推送模型服务发现和服务配置的推送模型不同特性服务配置服务发现推送内容完整配置文本变更的实例列表增量推送触发配置变更实例注册/注销/状态变更客户端缓存本地文件 内存ServiceInfoHolder内存 Map故障容错FailoverReactor 读本地文件FailoverReactor 读本地缓存一张图带走nacos-client 完整架构后台线程你的代码NamingService / ConfigService接口层api/服务发现naming/NamingClientProxyDelegate配置管理config/ClientWorkerNamingHttpClientProxyHTTP 兼容通道NamingGrpcClientProxygRPC 主通道ClientWorker连接 监听 缓存RpcClientgRPC 连接管理auth/Token 认证address/集群地址解析Nacos Server8848 9848HeartBeatThreadFailoverThreadCacheUpdateThread截图保存。从左到右你的代码 → 接口层 → 业务层服务发现/配置管理→ 通信层RpcClient→ 服务端。后台线程在业务层里常驻运行。不适用本文架构描述的情况1.x 客户端。如果你还在用 nacos-client 1.4.x架构差异很大没有 RpcClient、没有 gRPC 通道、ClientWorker 内部是 HTTP 长轮询而不是双向流。心跳机制是 BeatReactor 直接发 HTTP不经过 RpcClient。Spring Cloud Alibaba 2022.x。Spring Cloud Alibaba 在 2022.x 之后引入了 Spring Cloud LoadBalancer 替代 Ribbon服务发现的负载均衡层变了。但 nacos-client 内部的架构没变——变的是 Spring Cloud 那一层怎么调用 NamingService。你们在排查 Nacos 客户端问题时最常看哪个类的源码评论区留数字1ClientWorker 2NamingGrpcClientProxy 3BeatReactor 4ServiceInfoHolder 5还没看过客户端源码。
