---
title: Dubbo 服务目录与地址发现机制深度解析
author: Aias
date: 2026-07-08
coverImage: imgs/cover.png
---

# Dubbo 服务目录与地址发现机制深度解析

本文记录 Dubbo 消费端如何将注册中心和服务发现通知转化为集群层可见的调用器，重点分析 `Directory`、`RegistryDirectory`、`DynamicDirectory`、`ServiceDiscoveryRegistryDirectory` 以及提供者地址刷新机制。

## 在调用路径中的位置

`Directory` 是注册中心/服务发现与集群调用之间的地址视图层。正常消费者调用流程：

```text
注册中心 / 服务发现通知
  -> NotifyListener.notify(...)
  -> DynamicDirectory 刷新提供者地址
  -> AbstractDirectory 更新调用器快照和 RouterChain 状态
  -> ClusterInvoker 调用 directory.list(invocation)
  -> RouterChain 过滤候选者
  -> Cluster 容错策略选择调用行为
  -> LoadBalance 从路由后的候选列表中选择一个提供者
```

重要结论：提供者变更不会直接调用用户方法，而是修改目录快照。下一次消费者调用通过 `Directory.list(...)` 读取该快照。

`RegistryProtocol.doCreateInvoker(...)` 组装这个管道：它向目录注入注册中心和协议，按需注册消费者 URL，构建路由链，订阅目录到注册中心变更，最后返回 `cluster.join(directory, true)`。

![invocation-path.png](https://developer.qcloudimg.com/http-save/yehe-7136204/f6540867a3db0eafb1ef5302521f4607.png)

## 核心契约

### Directory

`Directory<T>` 是线程安全的 SPI，暴露以下接口：

- `list(Invocation)`：返回当前调用过滤后的调用器
- `getAllInvokers()`：返回原始注册中心/服务发现地址视图
- `getConsumerUrl()`：返回当前生效的消费者 URL
- `getRouterChain()`：暴露绑定到该目录的路由链
- `addInvalidateInvoker(...)`、`addDisabledInvoker(...)`、`recoverDisabledInvoker(...)`：支持连接验证和离线地址抑制

该契约刻意将原始地址与路由地址分离。路由在调用 `list(...)` 时发生，而非注册中心首次推送数据时。

### NotifyListener

`NotifyListener.notify(List<URL>)` 是注册中心推送契约。接口文档声明了塑造目录刷新逻辑的几个假设：

- 首次通知必须是订阅数据的完整通知
- 变更通知可按类别拆分，但每个类别载荷必须是完整的，而非增量
- 空数据必须用携带类别信息的 `empty://` URL 表示
- 通知顺序必须由注册中心实现保证

因为 Dubbo 依赖完整类别快照，`RegistryDirectory` 可以在每次推送时替换相关提供者 URL 集，而非对比任意增量事件。

### AddressListener

`AddressListener` 是模块作用域扩展点，可在调用器刷新前转换提供者地址。接口级和应用级目录都在收到通知后、将 URL 转换为调用器前，调用激活的 `AddressListener`。

这是关键扩展点：可以在路由和负载均衡看到地址前，添加、移除或重写地址。

## AbstractDirectory：本地快照与并发

![directory-structure.png](https://developer.qcloudimg.com/http-save/yehe-7136204/2fbf6123f8ae8fd19ee8b598cc93459f.png)

`AbstractDirectory` 拥有本地调用器快照：

- `invokers`：来自注册中心/服务发现的所有调用器
- `validInvokers`：`invokers` 减去重连中和禁用的调用器
- `invokersToReconnect`：临时失效的地址
- `disabledInvokers`：被离线/服务状态信号禁用的地址

`list(Invocation)` 获取一致快照，选择匹配的 `SingleRouterChain`，路由调用，返回不可修改结果。该方法现在协调两个锁：

- `routerChain.getLock().readLock()`，避免调用穿过正在地址刷新期间切换的链
- `invokerRefreshReadLock`，让调用能读取稳定的 `validInvokers` 快照，而刷新操作持有写锁

提供者刷新最终调用：

```text
refreshRouter(finalInvokers.clone(), () -> setInvokers(finalInvokers))
```

这意味着路由链刷新和目录调用器切换是耦合的。切换动作更新 `invokers`，重算 `validInvokers`，仅在路由链接受新地址集后才将调用器标记为已初始化。

连接验证添加另一层。如果提供者临时不可用，`addInvalidateInvoker(...)` 从 `validInvokers` 移除它并加入重连列表。调度任务稍后检查可用性，可能恢复它。地址刷新也能在提供者从注册中心快照消失时，从重连/禁用集移除过期条目。

## DynamicDirectory：注册中心感知基类

`DynamicDirectory` 扩展 `AbstractDirectory` 并实现 `NotifyListener`。它持有两种地址发现模式共享的注册中心集成状态：

- `registry` 和 `protocol`，由 `RegistryProtocol` 注入
- `subscribeUrl` 和 `registeredConsumerUrl`
- `directoryUrl`，动态覆盖后的生效消费者 URL
- `configurators`，活跃的覆盖规则
- `forbidden`，用于显式空地址通知后快速失败
- `serviceListener`，应用级服务发现使用
- `invokersChangedListener`，迁移逻辑用于观察地址刷新

默认 `doList(...)` 行为：

1. 如果 `forbidden` 且启用快速失败，抛出 forbidden `RpcException`
2. 如果目录代表多分组，返回合并的调用器列表
3. 否则将提供的调用器快照路由穿过选定的 `SingleRouterChain`

`invokersChanged()` 是地址刷新到迁移和可用性观察者的桥梁。它刷新 `validInvokers`，标记调用器已变更，如有监听器则通知。

## RegistryDirectory：接口级发现

`RegistryDirectory` 是经典接口级目录。它消费来自以下类别的提供者 URL 通知：

- `providers`
- `routers`
- `configurators`
- 动态配置器类别

### 通知处理

![notify-flow.png](https://developer.qcloudimg.com/http-save/yehe-7136204/f4eb0c048bd2a5f9b2e5fd00e081108d.png)

`RegistryDirectory.notify(...)` 是同步的，按此顺序处理通知：

1. 如果目录已销毁，忽略通知
2. 过滤无效/不支持类别
3. 按类别分组 URL
4. 将配置器 URL 转换为 `Configurator`
5. 将路由器 URL 转换为 `Router` 并加入路由链
6. 提取提供者 URL
7. 让提供者 URL 穿过激活的 `AddressListener`
8. 调用 `refreshOverrideAndInvoker(providerURLs)`

`refreshOverrideAndInvoker(...)` 从原始消费者 URL 加活跃配置器重算 `directoryUrl`，然后调用 `refreshInvoker(...)`。

### 提供者刷新

`refreshInvoker(List<URL>)` 处理提供者地址集：

- 单个 `empty://` URL 意味注册中心显式说明无提供者。目录设置 `forbidden = true`，用空列表刷新路由链，销毁所有调用器
- 无 `empty://` 的空白列表被视为可疑。如有缓存提供者 URL，从缓存恢复作为空地址保护
- 非空通知在调用器转换前去重
- 当合并提供者 URL 未变时，从 `urlInvokerMap` 复用现有调用器
- 新增或变更 URL 调用 `protocol.refer(serviceType, url)`
- 移除的 URL 在新映射安装后销毁

缓存键是有效的合并提供者 URL。任何通过合并/配置器处理的参数变更都可能触发重引用。

### URL 合并与覆盖

`toInvokers(...)` 执行协议验证后调用 `mergeUrl(...)`。合并顺序实际为：

```text
动态覆盖 > 系统/消费者配置 > 提供者 URL
```

对于正常 URL，消费者参数合并到提供者 URL，然后应用配置器。对于服务地址 URL，配置器可通过 `DubboServiceAddressURL` 包装服务地址 URL。

合并时添加 `check=false`，让 Dubbo 即使提供者连接暂不可用也能创建调用器。可用性由目录连接机制管理，而非让初始刷新失败。

## ServiceDiscoveryRegistryDirectory：应用级发现

`ServiceDiscoveryRegistryDirectory` 处理应用级服务发现。它接收实例衍生的 `InstanceAddressURL` 而非普通接口级提供者 URL。

高层刷新路径镜像 `RegistryDirectory`：

```text
notify(instanceUrls)
  -> AddressListener.notify(...)
  -> refreshOverrideAndInvoker(instanceUrls)
  -> refreshInvoker(instanceUrls)
  -> toInvokers(...)
  -> refreshRouter(... setInvokers ...)
  -> destroy unused invokers
```

转换规则不同：

- 缓存键是 `ProtocolServiceKeyWithAddress`，而非原始 URL
- 目录从 `InstanceAddressURL` 读取提供者元数据
- 它将元数据服务条目与消费者的 `ProtocolServiceKey` 匹配
- 如果消费者未指定协议，首先偏好协议匹配 `preferred-protocol` 的服务条目；若无匹配，回退到非额外主协议
- 如果实例包含多个匹配服务键，或匹配服务键与消费者键不同，调用器包装为带定制消费者 URL 的 `InstanceWrappedInvoker`
- `urlChanged(...)` 比较实例身份、覆盖参数和元数据服务信息来决定是否重引用

因此应用级发现将实例地址加元数据映射为一个或多个调用器。一个物理实例可在多协议、多版本或多分组匹配时贡献多个逻辑调用目标。

## 提供者地址刷新机制

![refresh-flow.png](https://developer.qcloudimg.com/http-save/yehe-7136204/e66bf1838efccfad0735976d89781f05.png)

完整提供者刷新序列：

1. 注册中心实现收到提供者/地址变更
2. 注册中心在订阅目录上调用 `NotifyListener.notify(...)`
3. 目录过滤类别数据或实例 URL
4. 激活的 `AddressListener` 可重写地址集
5. 动态配置器重写有效的消费者/提供者视图
6. 目录去重地址
7. 目录创建旧调用器映射副本
8. `toInvokers(...)` 复用未变调用器，引用新增/变更的
9. 目录创建最终 `BitList<Invoker<T>>`
10. `refreshRouter(...)` 刷新路由状态并通过 `setInvokers(...)` 原子切换目录调用器快照
11. 旧映射中剩余的调用器被销毁
12. `invokersChanged()` 刷新有效调用器并通知迁移/监听器代码
13. 下一次消费者调用通过 `Directory.list(...)` 读取新快照

此顺序重要。Dubbo 在销毁旧的未用调用器前安装新调用器视图，避免仅因刷新进行中导致无可用地址的空窗。

## 空地址语义

Dubbo 区分两种情况：

- **显式空**：单个 `empty://` URL。表示该类别无提供者可用。目录清空调用器，可能快速失败
- **意外空白列表**：无 `empty://` 的空列表。视为注册中心或通知异常。接口级发现尽可能从缓存恢复提供者 URL；应用级发现忽略该空白通知作为保护

此区分防止瞬态注册中心故障清空消费者地址池。

## 路由与负载均衡顺序

目录刷新在路由和负载均衡之前发生，但路由在刷新期间未完全执行。刷新为新地址集准备路由链状态。每次调用的路由仍发生在 `Directory.list(...)`，因为运行时路由器可检查当前调用。

最终运行时顺序：

```text
目录地址快照
  -> 路由链
  -> 集群容错
  -> 负载均衡
```

因此：

- 注册中心通知移除的提供者不会到达负载均衡器
- 目录保留但路由规则过滤的提供者不会在本次调用到达负载均衡器
- 负载均衡器只从地址刷新和路由都存活的调用器中选择

## 历史演进

### 目录超越列表

`efa6900bb1`（2021-11-03，"Add connectivity validation, router snapshot"）扩展 `Directory` 契约，加入原始调用器访问、失效、禁用和恢复操作。同时引入目录级连接验证和分离的全/有效调用器快照。这是 `Directory` 明确成为活跃可用性把关者而非注册中心列表包装器的关键点。

`c5fc78fc9f`（2021-11-04，"Add get raw invokers in Directory Support"）延续此方向，显式化原始调用器视图。

### 空地址保护

`b094665009`（2021-12-15，"support empty address protection"）引入当前显式 `empty://` 与意外空列表的区分。接口级发现收到无 `empty://` 的空列表时复用缓存调用器 URL；应用级发现忽略此类空列表。

这解释了为何当前刷新代码同时有"清空一切"和"忽略/保护"分支。

### 服务发现并发

`7a5d04a169`（2022-02-23，"Fix concurrency issues of service discovery"）修复服务发现通知上下文处理，通过 `DynamicDirectory` 暴露 `ServiceInstancesChangedListener`。反映此层反复出现的风险：通知线程非普通调用线程，但下游刷新逻辑仍依赖正确的消费者上下文。

`2170f0fa90`（2025-09-25，"fix thread safety issue of ConsumerConfigurationListener"）将应用级配置监听器集合改为 `CopyOnWriteArrayList`。`58d738682f`（2025-11-18，"fix: thread safety RegistryDirectory"）为接口级 `RegistryDirectory` 做同风格修复。配置变更可在目录增删时到达，故监听器迭代必须容忍并发修改。

### 路由链与目录切换一致性

`b56687957e`（2023-01-14，"Fix invokers has changed when router chain switch"）通过 `AbstractDirectory.refreshRouter(...)` 集中路由刷新，改变目录实现传递切换动作：

```text
refreshRouter(finalInvokers.clone(), () -> setInvokers(finalInvokers))
```

这是刷新代码现在耦合路由链更新和目录快照更新的关键历史原因。缺陷类别是调用器列表与为该列表构建的路由链不匹配。

`dcb0db7f33`（2026-01-12，"During the service provider's release period, concurrent read routes from consumers were rejected"）将简单刷新锁替换为公平 `ReentrantReadWriteLock`，添加读路径超时诊断。表明提供者发布期间的地址刷新可与真实消费者调用竞争；目录必须允许并发读者同时仍序列化刷新修改。

### 重复地址通知

`a35af2742a`（2025-05-16，"Remove duplicated invokers in registry notification"）为 `RegistryDirectory` 和 `ServiceDiscoveryRegistryDirectory` 添加去重。否则注册中心可能推送重复提供者 URL 或实例 URL，目录会构建重复调用器，放大到同一提供者的流量。

### 配置时序与接口级覆盖

`21c29089cd`（2025-11-20，"interface-level timeout and retry configurations become invalid after caller application is restarted"）将配置监听器注册移到 `RegistryDirectory` 的注册中心订阅前。

顺序重要，因为初始订阅可同步触发提供者刷新。如果配置监听器在订阅后安装，首批调用器集可能不带接口级超时/重试覆盖。

### 应用级发现的偏好协议

`7c7788d8b7`（2024-11-07，"Add preferred protocol support for application service discovery"）改变 `ServiceDiscoveryRegistryDirectory`，在消费者未显式选择协议时，首先按 `preferred-protocol` 匹配元数据条目，然后回退到默认主协议。这就是应用级发现现在比接口级提供者 URL 转换有更丰富匹配步骤的原因。

## 失败模式与设计影响

### 注册中心推送质量直接影响调用候选者

Dubbo 假设完整类别快照和有序通知。如果注册中心推送部分提供者数据当作完整数据，目录可移除有效提供者。空地址保护只覆盖无 `empty://` 的空白列表；无法推断非空但不完整列表是错误的。

### AddressListener 可改变地址池

`AddressListener` 在调用器转换前执行。此处扩展可改变路由和负载均衡观察的提供者集。使其对分区、网格或迁移集成强大，但也意味着此类扩展属于地址发现信任边界的一部分。

### URL 键稳定性控制重引用成本

接口级发现按有效提供者 URL 复用调用器。如果动态配置变更产生不同 URL 键，Dubbo 会重引用提供者并销毁旧调用器。频繁噪音参数变更可因此导致不必要的连接震荡。

应用级发现将键窄化为服务键加地址，然后用 `urlChanged(...)` 比较实例身份和元数据。减少部分 URL 字串震荡，但使元数据正确性更重要。

### 协议过滤可清空目录

两种目录实现都拒绝不支持协议。接口级发现还按消费者请求协议过滤。如果所有提供者地址被过滤掉，目录拒绝用转换失败导致的空映射替换当前映射。日志指出可能的消费者/提供者协议不匹配。

### 刷新与调用并发

提供者发布、注册中心推送、配置更新和消费者调用可重叠。当前锁模型存在以防止三类缺陷：

- 用错误路由链路由快照
- 刷新修改 `validInvokers` 时读取它
- 新调用器快照安装前销毁旧调用器

未来任何目录刷新变更都应保留此顺序。

## 实践调试清单

消费者未见预期提供者时，按此顺序检查：

1. 注册中心是否发送 `empty://` 或空白/部分 URL 列表？
2. 类别过滤是否将 URL 放入 `providers` 或丢弃为不支持？
3. `AddressListener` 是否移除或重写地址？
4. 配置器是否改变有效提供者或消费者 URL？
5. 协议过滤是否拒绝提供者协议？
6. `toInvokers(...)` 是否在 `protocol.refer(...)` 时失败？
7. 目录刷新后路由规则是否过滤调用器？
8. 连接验证是否将调用器从 `validInvokers` 移至 `invokersToReconnect`？
9. 对于应用级发现，实例元数据是否包含预期的服务键、协议、端口、分组和版本？

## 总结

Dubbo 服务目录是并发敏感的地址投影层。注册中心不直接喂养负载均衡器，而是喂养 `DynamicDirectory`，后者归一化通知数据、应用地址监听器和配置器、将地址转换为可复用调用器、刷新路由状态、向集群调用暴露稳定的路由快照。

`RegistryDirectory` 以 URL/类别为中心，代表接口级发现。`ServiceDiscoveryRegistryDirectory` 以实例/元数据为中心，代表应用级发现。刷新管道刻意相似，但缓存键和匹配逻辑不同，因为发现模型不同。

本文记录 Dubbo 消费端如何将注册中心和服务发现通知转化为集群层可见的调用器，重点分析 Directory、RegistryDirectory、DynamicDirectory、ServiceDiscoveryRegistryDirectory 以及提供者地址刷新机制。

Dubbo 服务目录与地址发现机制深度解析

软件研发

后端

架构设计

开发工具

本文深度解析Dubbo服务目录与地址发现机制，涵盖Directory、RegistryDirectory等核心组件，详细剖析提供者地址刷新流程。重点讲解注册中心通知如何转化为调用器快照，以及路由链与目录切换的同步机制，帮助开发者理解Dubbo服务发现与调用的底层原理。

负载均衡

代码解释

路由器

路由

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Dubbo 服务目录与地址发现机制深度解析-腾讯云开发者社区-腾讯云

Dubbo 服务目录与地址发现机制深度解析

Dubbo 服务目录与地址发现机制深度解析

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐