源码指南 on Apache Dubbo

架构

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

快速开始 RPC 应用：dubbo-go-samples/helloworld
基于注册中心的微服务应用：dubbo-go-samples/registry/nacos
多协议应用：dubbo-go-samples/rpc/multi-protocols

Dubbo Go 当前围绕几个运行时概念组织：应用实例、provider、consumer、protocol、registry、metadata 和治理扩展。现在的应用通常通过 dubbo.go、server、client 中的 API 入口构建；使用配置文件的场景仍然会走 config.RootConfig。

主要运行层次

层次	主要包	职责
应用实例	`dubbo.go`, `options.go`	持有 application、protocol、registry、metadata、metrics、tracing、router、shutdown 等选项。
Provider API	`server`	注册 service handler，构造 service options，创建 invoker 并暴露服务。
Consumer API	`client`	创建 client，引用服务，创建生成代码服务或泛化服务，并发起远程调用。
Protocol	`protocol/base`, `protocol/triple`, `protocol/dubbo`, `protocol/rest`	Provider 侧将 invoker 转为网络服务，consumer 侧将 invoker 转为网络调用。
Registry 与发现	`registry`, `registry/protocol`, `registry/servicediscovery`, `registry/directory`	负责注册、订阅、服务发现和注册中心驱动的调用。
Metadata	`metadata`, `metadata/report`, `metadata/mapping`	负责服务定义、service-to-application 映射和 metadata 上报。
治理扩展	`filter`, `cluster`, `cluster/router`, `cluster/loadbalance`, `common/extension`	提供 filter、router、load balance、cluster 策略和扩展注册。

Provider 流程

当前 server API 下，provider 通常会经历以下流程：

网络协议

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

Triple RPC：dubbo-go-samples/rpc/triple
多协议服务：dubbo-go-samples/rpc/multi-protocols
gRPC 互通：dubbo-go-samples/rpc/grpc

在当前 Dubbo Go 中，protocol 层是 invocation 模型和底层网络协议之间的桥梁。它一方面负责把 provider 暴露成网络服务，另一方面负责把 consumer 侧的引用转换成可调用的远程 invoker。

核心协议抽象

当前协议接口定义在 protocol/base/base_protocol.go：

type Protocol interface {
	Export(invoker Invoker) Exporter
	Refer(url *common.URL) Invoker
	Destroy()
}

它的职责很直接：

Export：把 provider 侧 invoker 暴露成网络服务
Refer：为目标 URL 创建 consumer 侧 invoker
Destroy：销毁该协议持有的 invoker 和 exporter

此外还有一个可选能力：

type RegistryUnregisterer interface {
	UnregisterRegistries()
}

它主要用于优雅停机阶段，让协议在完整 teardown 之前，先把已经暴露出去的服务从注册中心摘除。

Provider 侧流程

在 provider 侧，Dubbo Go 通常会经过下面这条链路：

server.Register(...) 或 server.RegisterService(...) 创建 service metadata 和 invoker。
ServiceOptions.Export() 选择 protocol 和 registry 行为。
具体协议实现调用 Export(invoker)。
暴露后的服务开始监听配置好的网络端点。

不同协议提供不同的传输层和编解码方式，但都会遵循同一个 Export 契约。

注册中心

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

Nacos 注册中心：dubbo-go-samples/registry/nacos
Zookeeper 注册中心：dubbo-go-samples/registry/zookeeper
应用级服务发现：dubbo-go-samples/registry/nacos

核心 Registry 接口

主接口定义在 registry/registry.go：

type Registry interface {
	common.Node
	Register(url *common.URL) error
	UnRegister(url *common.URL) error
	Subscribe(*common.URL, NotifyListener) error
	UnSubscribe(*common.URL, NotifyListener) error
	LoadSubscribeInstances(*common.URL, NotifyListener) error
}

和旧版说明相比，一个明显变化是 LoadSubscribeInstances(...) 已经进入接口契约。原因是订阅本身是异步的，Dubbo Go 在正式进入异步通知流之前，可能需要先同步加载一次初始实例列表。

当前职责范围

现在 registry 层覆盖了几类紧密相关的职责：

provider 注册与反注册
consumer 订阅与取消订阅
异步更新前的初始实例加载
应用级服务发现
与 registry 绑定的 metadata 上报

从源码目录看，相关主包包括：

registry
registry/protocol
registry/servicediscovery
registry/directory

注册模式

当前 Dubbo Go 通过 registry/options.go 支持多种注册模型：

registry.WithRegisterService()
registry.WithRegisterInterface()
registry.WithRegisterServiceAndInterface()

它们分别对应：

service：注册应用级实例
interface：注册接口级 provider URL
all：迁移阶段同时注册两种模型

这也是它和早期文档的一个关键差异。旧文档大多只讲了接口级注册。

3.x 核心能力

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

Triple 协议：dubbo-go-samples/rpc/triple
基于 Nacos 的应用级服务发现：dubbo-go-samples/registry/nacos
Service Mesh 部署：dubbo-go-samples/mesh

Dubbo Go 3.x 的核心能力已经围绕 Triple 协议、应用级服务发现、metadata 驱动的服务自省，以及 SDK 侧治理能力展开。这些内容不再只是 3.0 版本的新特性，而是当前 Dubbo Go 应用的常规开发模型。

Triple 协议

Triple 是 Dubbo Go 3.x 推荐使用的 RPC 协议，主要实现位于：

protocol/triple
protocol/triple/triple_protocol
tools/protoc-gen-go-triple

Triple 基于 HTTP/1.1 和 HTTP/2 语义，并在线路协议上兼容 gRPC。对于 protobuf 服务，用户先定义 .proto 文件，再通过 protoc-gen-go 和 protoc-gen-go-triple 生成 Go 代码，最后将生成的 handler 注册到 Dubbo Go server。

运行时链路遵循 Dubbo 通用协议抽象：

provider 侧：server.Register(...) 构造 service options 和 invoker，再通过协议 Export 暴露服务；
consumer 侧：生成的 client 调用 client.Connection，由它构造 invocation 并委托给协议 Refer 返回的 invoker；
request header、response header、trailer 等 metadata 通过 Triple metadata API 暴露。

应用级服务发现

应用级服务发现是当前 Dubbo Go 默认的服务发现模型。provider 注册应用实例和 metadata；consumer 解析 service 到 application 的映射，再通过 metadata 还原可调用的服务 URL。

泛化调用

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

泛化调用示例：dubbo-go-samples/generic
Triple 示例：dubbo-go-samples/rpc/triple

当前 Dubbo Go 的泛化调用主要围绕 client.NewGenericService(...) 和 filter/generic.GenericService 展开。早期基于 ReferenceConfigBuilder、GenericLoad()、GetRPCService() 的示例属于兼容旧 API 的写法，已经不是推荐入口。

核心 API

主要运行时入口在 client/client.go：

genericService, err := cli.NewGenericService(
	"org.apache.dubbo.samples.UserProvider",
	client.WithProtocolTriple(),
	client.WithSerialization(constant.Hessian2Serialization),
	client.WithURL("tri://127.0.0.1:20000"),
)

NewGenericService(...) 默认会做三件事：

设置 NONIDL
打开 generic invocation
使用 hessian2 序列化

它内部会创建 filter/generic.GenericService，然后接入 Dubbo Go 正常的 reference 和 invocation 流程。

GenericService

核心类型如下：

type GenericService struct {
	Invoke func(ctx context.Context, methodName string, types []string, args []hessian.Object) (any, error) `dubbo:"$invoke"`
}

它和 Dubbo 的泛化调用模型保持一致：调用方提供：

方法名
参数类型名列表
参数值列表

框架再把这些内容编码成对远端服务的 $invoke 请求。

泛化调用兼容说明

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

泛化调用示例：dubbo-go-samples/generic

这个页面主要保留给旧链接兼容使用。

当前 Dubbo Go 请优先阅读泛化调用。旧示例里使用的：

config.NewReferenceConfigBuilder()
GenericLoad()
GetRPCService()

属于早期以配置对象为中心的 API 路径。现在更推荐的运行时入口是：

client.NewGenericService(...)
filter/generic.GenericService.Invoke(...)
filter/generic.GenericService.InvokeWithType(...)

如果你要找一个可以直接参考的完整示例，优先看 dubbo-go-samples/generic。

AOP 与可扩展机制

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

自定义 filter：dubbo-go-samples/filter/custom
条件路由：dubbo-go-samples/router/condition
标签路由：dubbo-go-samples/router/tag

Dubbo Go 通过 Go 包初始化和统一的扩展注册中心，来承载大部分可插拔能力。filter、router、protocol、registry、load balance、cluster 策略、tracing exporter、metadata report 等能力，都是按这个模型加载的。

extension 注册中心

当前实现位于 common/extension。它已经不再依赖每个类型单独维护的原始 map，而是统一使用泛型注册中心：

var loadbalances = NewRegistry[func() loadbalance.LoadBalance]("loadbalance")

func SetLoadbalance(name string, fcn func() loadbalance.LoadBalance) {
	loadbalances.Register(name, fcn)
}

func GetLoadbalance(name string) loadbalance.LoadBalance {
	return loadbalances.MustGet(name)()
}

同样的模式也用在：

common/extension/filter.go
common/extension/protocol.go
common/extension/registry.go
common/extension/router_factory.go

这样做之后，Dubbo Go 的扩展注册模型更统一，也支持某些类别上的注销、列举已注册名称等辅助能力。

`init()` 的作用

内置实现通常都会在自己的包里通过 init() 完成注册：

func init() {
	extension.SetLoadbalance(constant.LoadBalanceKeyRandom, NewRandomLoadBalance)
}

运行时里很多能力都遵循这个模式：

protocol/triple/triple.go 注册 Triple
protocol/dubbo/dubbo_protocol.go 注册 Dubbo
protocol/rest/rest_protocol.go 注册 REST
registry/nacos/registry.go、registry/zookeeper/registry.go、registry/etcdv3/registry.go 注册 registry
filter/generic/filter.go、filter/metrics/filter.go、filter/graceful_shutdown/... 注册 filter
cluster/router/condition/factory.go、cluster/router/tag/factory.go、cluster/router/script/factory.go 注册 router factory

只要这些包被导入，框架后续就能按名称查找到对应实现。

应用和接口

Mon, 01 Jan 0001 00:00:00 +0000

相关示例：

Hello world 应用：dubbo-go-samples/helloworld
基于 YAML 的配置：dubbo-go-samples/config_yaml
基于注册中心的应用：dubbo-go-samples/registry/nacos

当前 Dubbo Go 依然保留“应用级配置”和“接口级服务引用”这两个层次，但它的运行时模型已经比早期版本里那种简单的“application vs interface”说明更完整。现在真正的源码入口，是 options.go 里的应用实例选项，以及兼容配置文件模式的 config/root_config.go。

应用级配置

应用级配置会被同一个 Dubbo Go 进程里的所有服务和引用共享。

在配置文件模式下，这套模型由 config.RootConfig 表达，主要字段包括：

Application
Protocols
Registries
ConfigCenter
MetadataReport
Provider
Consumer
Otel
Metrics
Tracing
Logger
Shutdown
Router
TLSConfig

在 API 模式下，对应的是 options.go 里的 InstanceOptions，它通常通过下面这些 helper 填充：

dubbo.WithProtocol(...)
dubbo.WithRegistry(...)
dubbo.WithConfigCenter(...)
dubbo.WithMetadataReport(...)
dubbo.WithMetrics(...)
dubbo.WithTracing(...)
dubbo.WithShutdown(...)
dubbo.WithRouter(...)
dubbo.WithRemoteMetadata()
dubbo.WithMetadataServiceProtocol(...)

这些选项描述的是整个应用实例的运行环境，而不是某一个单独服务。

接口级配置

接口级配置则绑定在单个暴露服务或单个远程引用上。

在 provider 侧，核心单位是注册出来的 service：

server.Register(...)
server.RegisterService(...)
server.ServiceOptions

这一层承载接口名、实现 handler、protocol ID、registry ID、序列化方式，以及服务 metadata 等信息。

源码指南 on Apache Dubbo

架构

主要运行层次

Provider 流程

网络协议

核心协议抽象

Provider 侧流程

注册中心

核心 Registry 接口

当前职责范围

注册模式

3.x 核心能力

Triple 协议

应用级服务发现

泛化调用

核心 API

GenericService

泛化调用兼容说明

AOP 与可扩展机制

extension 注册中心

init() 的作用

应用和接口

应用级配置

接口级配置

`init()` 的作用