dubbo

README

Apache Dubbo for Golang

---

English | 中文

Apache Dubbo-go is a high-performance RPC and microservice framework compatible with other Dubbo language implementations. It leverages Golang's concurrency features to provide efficient service governance, including service discovery, load balancing, and traffic management. Dubbo-go supports multiple protocols, such as Dubbo, JSONRPC, Triple(gRPC-compatible), gRPC, HTTP, HTTP2, and HTTP/3 (experimental), ensuring seamless integration in heterogeneous environments.

You can visit the official website for more information.

Recent Updates

For detailed changes, refer to CHANGELOG.md.

• 3.3.1: Optimized configuration hot-reloading with content-based caching to prevent redundant notifications. Added experimental HTTP/3 support, Apollo integration, and Triple protocol OpenAPI generation. Fixed critical race conditions in service discovery under high-concurrency.

• 3.3.0: Introduced script routing, multi-destination conditional routing, Triple protocol keepalive and connection pooling, Nacos multi-category subscriptions, and enhancements for observability and interoperability.

Getting started

Prerequisites

• Go 1.24 or later (recommended for compatibility with recent updates).

Installation

To install Dubbo-go, use the following command:

go get dubbo.apache.org/dubbo-go/v3@latest

Quick Example

You can learn how to develop a dubbo-go RPC application step by step in 5 minutes by following our Quick Start demo.

It's as simple as the code shown below, you define a service with Protobuf, provide your own service implementation, register it to a server, and start the server.

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
	resp := &greet.GreetResponse{Greeting: req.Name}
	return resp, nil
}

func main() {
	srv, _ := server.NewServer(
		server.WithServerProtocol(
			protocol.WithPort(20000),
			protocol.WithTriple(),
		),
	)

	_ := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{})

	if err := srv.Serve(); err != nil {
		logger.Error(err)
	}
}

After the server is up and running, call your service via cURL:

curl \
    --header "Content-Type: application/json" \
    --data '{"name": "Dubbo"}' \
    http://localhost:20000/greet.GreetService/Greet

Or, you can start a standard dubbo-go client to call the service:

func main() {
	cli, _ := client.NewClient(
		client.WithClientURL("127.0.0.1:20000"),
	)

	svc, _ := greet.NewGreetService(cli)

	resp, _ := svc.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})
	
	logger.Infof("Greet response: %s", resp.Greeting)
}

See the samples for detailed information on usage. Next, learn how to deploy, monitor and manage the traffic of your dubbo-go application by visiting the official website.

Features

Dubbo-go provides robust service governance capabilities:

• RPC Protocols: Triple, gRPC compatible and HTTP-friendly
• Service Discovery: Nacos, Zookeeper, Etcd, Polaris-mesh.
• Load Balance: Adaptive, Random, RoundRobin, LeastActive, ConsistentHash
• Traffic Management: traffic split, timeout, rate limiting, canary release
• Configuration: yaml file, dynamic configuration(Nacos, Apollo, Zookeeper, etc.).
• Observability: Metrics (Prometheus), tracing (OpenTelemetry v1.21.0+ with insecure options and standardized span names), logging (with service registration lifecycle events).
• HA Strategy: Failover, Failfast, Failsafe/Failback, Available, Broadcast, Forking.
• Interoperability: Full compatibility with Apache Dubbo (Java) via Triple protocol generic calls, group/version wildcard matching, and TLS API redesign.

️ Tools

The tools/ directory and the dubbogo/tools repository provide several utilities to streamline your Dubbo-Go development experience.

dubbo-go-schema

A tool that provides JSON Schema for Dubbo-Go configuration files. This simplifies the configuration process by enabling editor assistance.

Features:

• Intelligent Assistance: Enables code completion, hints, and real-time validation for configuration files in supported IDEs.
• Simplified Configuration: Helps you write valid and accurate configurations with ease.

For usage details, see the dubbo-go-schema README.

dubbogo-cli

A comprehensive command-line tool for bootstrapping, managing, and debugging your Dubbo-Go applications.

Features:

• Project Scaffolding: Quickly create new application templates.
• Tool Management: Install and manage essential development tools.
• Interface Debugging: Provides commands to debug your services.

• dubbogo-cli
• dubbogo-cli-v2

protoc-gen-go-triple

A protoc plugin that generates golang code for the Triple protocol from your .proto (Protocol Buffer) definition files.

Features:

• Code Generation: Generates golang client and server stubs for the Triple protocol.
• Seamless Integration: Works alongside the official protoc-gen-go to produce both Protobuf message code (.pb.go) and Triple interface code (.triple.go).

Note: This tool replaces the deprecated protoc-gen-dubbo3grpc and deprecated protoc-gen-go-triple.

For usage details, see the protoc-gen-go-triple README.

imports-formatter

This is a plugin for dubbo-go developers. A code formatting tool that organizes golang import blocks according to the Dubbo-Go community style guide.

Features:

• Automatic Formatting: Splits import statements into three distinct groups: golang standard library, third-party libraries, and internal project packages.
• Code Consistency: Enforces a clean and consistent import style across the codebase.

For usage details, see the imports-formatter README.

Ecosystem

• dubbo-go-samples
• dubbo-go-pixiu which acting as a proxy to solve Dubbo multi-language interoperability
• Interoperability with Dubbo Java
• Protoc-gen-go-triple
• Console, under development

Documentation

• Official Website: https://dubbo.apache.org/
• Dubbo-go Documentation: https://dubbo.apache.org/docs/dubbo-go/
• CHANGELOG: https://github.com/apache/dubbo-go/blob/main/CHANGELOG.md

Community

• GitHub Issues: https://github.com/apache/dubbo-go/issues
• Mailing Lists: https://dubbo.apache.org/en/community/

Contributions, issues, and discussions are welcome. Please visit CONTRIBUTING for details on submitting patches and the contribution workflow.

Contact

Join our discussion group through Ding talk, WeChat, or Discord.

discord https://discord.gg/C5ywvytg

User List

If you are using apache/dubbo-go and think that it helps you or want to contribute code for Dubbo-go, please add your company to the user list to let us know your needs.

See more user cases

License

Apache Dubbo-go software is licensed under the Apache License Version 2.0. See the LICENSE file for details.

Documentation

Overview

Package dubbo provides the Go implementation for Dubbo, an RPC and microservice framework.

See dubbo.apache.org for more information about Dubbo.

Index

• func AllowHotReloadContains(substr string)
• func AllowHotReloadExact(key string)
• func AllowHotReloadPrefix(prefix string)
• func CompatGlobalProtocolConfig(c *config.ProtocolConfig) *global.ProtocolConfig
• func CompatGlobalProtocolConfigMap(m map[string]*config.ProtocolConfig) map[string]*global.ProtocolConfig
• func CompatGlobalServiceConfig(c *config.ServiceConfig) *global.ServiceConfig
• func CompatGlobalTLSConfig(c *config.TLSConfig) *global.TLSConfig
• func GetConfigResolver(conf *loaderConf) *koanf.Koanf
• func GetConsumerConnection(interfaceName string) (*client.Connection, error)
• func Load(opts ...LoaderConfOption) error
• func NewLoaderConf(opts ...LoaderConfOption) *loaderConf
• func SetConsumerService(svc common.RPCService)
• func SetConsumerServiceWithInfo(svc common.RPCService, info *client.ClientInfo)
• func SetProviderService(svc common.RPCService)
• func SetProviderServiceWithInfo(svc common.RPCService, info *common.ServiceInfo)
• func StopFileWatcher()
• type Instance
  • func NewInstance(opts ...InstanceOption) (*Instance, error)
  • func (ins *Instance) NewClient(opts ...client.ClientOption) (*client.Client, error)
  • func (ins *Instance) NewServer(opts ...server.ServerOption) (*server.Server, error)
• type InstanceOption
  • func WithConfigCenter(opts ...config_center.Option) InstanceOption
  • func WithEnvironment(environment string) InstanceOption
  • func WithGroup(group string) InstanceOption
  • func WithLogger(opts ...logger.Option) InstanceOption
  • func WithMetadataReport(opts ...metadata.ReportOption) InstanceOption
  • func WithMetadataServicePort(port int) InstanceOption
  • func WithMetadataServiceProtocol(protocol string) InstanceOption
  • func WithMetrics(opts ...metrics.Option) InstanceOption
  • func WithModule(module string) InstanceOption
  • func WithName(name string) InstanceOption
  • func WithOrganization(organization string) InstanceOption
  • func WithOwner(owner string) InstanceOption
  • func WithProtocol(opts ...protocol.ServerOption) InstanceOption
  • func WithRegistry(opts ...registry.Option) InstanceOption
  • func WithRemoteMetadata() InstanceOption
  • func WithRouter(opts ...router.Option) InstanceOption
  • func WithShutdown(opts ...graceful_shutdown.Option) InstanceOption
  • func WithTLS(opts ...tls.Option) InstanceOption
  • func WithTag(tag string) InstanceOption
  • func WithTracing(opts ...trace.Option) InstanceOption
  • func WithVersion(version string) InstanceOption
• type InstanceOptions
  • func (rc *InstanceOptions) CloneApplication() *global.ApplicationConfig
  • func (rc *InstanceOptions) CloneConfigCenter() *global.CenterConfig
  • func (rc *InstanceOptions) CloneConsumer() *global.ConsumerConfig
  • func (rc *InstanceOptions) CloneCustom() *global.CustomConfig
  • func (rc *InstanceOptions) CloneLogger() *global.LoggerConfig
  • func (rc *InstanceOptions) CloneMetadataReport() *global.MetadataReportConfig
  • func (rc *InstanceOptions) CloneMetrics() *global.MetricsConfig
  • func (rc *InstanceOptions) CloneOtel() *global.OtelConfig
  • func (rc *InstanceOptions) CloneProfiles() *global.ProfilesConfig
  • func (rc *InstanceOptions) CloneProtocols() map[string]*global.ProtocolConfig
  • func (rc *InstanceOptions) CloneProvider() *global.ProviderConfig
  • func (rc *InstanceOptions) CloneRegistries() map[string]*global.RegistryConfig
  • func (rc *InstanceOptions) CloneRouter() []*global.RouterConfig
  • func (rc *InstanceOptions) CloneShutdown() *global.ShutdownConfig
  • func (rc *InstanceOptions) CloneTLSConfig() *global.TLSConfig
  • func (rc *InstanceOptions) Prefix() string
• type LoaderConfOption
  • func WithBytes(bytes []byte) LoaderConfOption
  • func WithDelim(delim string) LoaderConfOption
  • func WithGenre(suffix string) LoaderConfOption
  • func WithInstanceOptions(opts *InstanceOptions) LoaderConfOption
  • func WithPath(path string) LoaderConfOption
  • func WithSuffix(suffix file.Suffix) LoaderConfOption

Functions

func AllowHotReloadContains

func AllowHotReloadContains(substr string)

func AllowHotReloadExact

func AllowHotReloadExact(key string)

func AllowHotReloadPrefix

func AllowHotReloadPrefix(prefix string)

func CompatGlobalProtocolConfig

func CompatGlobalProtocolConfig(c *config.ProtocolConfig) *global.ProtocolConfig

func CompatGlobalProtocolConfigMap

func CompatGlobalProtocolConfigMap(m map[string]*config.ProtocolConfig) map[string]*global.ProtocolConfig

func CompatGlobalServiceConfig

func CompatGlobalServiceConfig(c *config.ServiceConfig) *global.ServiceConfig

func CompatGlobalTLSConfig

func CompatGlobalTLSConfig(c *config.TLSConfig) *global.TLSConfig

func GetConfigResolver

func GetConfigResolver(conf *loaderConf) *koanf.Koanf

GetConfigResolver get config resolver

func GetConsumerConnection

func GetConsumerConnection(interfaceName string) (*client.Connection, error)

func Load

func Load(opts ...LoaderConfOption) error

func NewLoaderConf

func NewLoaderConf(opts ...LoaderConfOption) *loaderConf

func SetConsumerService

func SetConsumerService(svc common.RPCService)

func SetConsumerServiceWithInfo

func SetConsumerServiceWithInfo(svc common.RPCService, info *client.ClientInfo)

SetConsumerServiceWithInfo sets the consumer service with the client information.

func SetProviderService

func SetProviderService(svc common.RPCService)

func SetProviderServiceWithInfo

func SetProviderServiceWithInfo(svc common.RPCService, info *common.ServiceInfo)

SetProviderServiceWithInfo sets the provider service with the server information.

func StopFileWatcher

func StopFileWatcher()

StopFileWatcher Stop file listener

Types

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance is the highest layer conception that user could touch. It is mapped from RootConfig. When users want to inject global configurations and configure common modules for client layer and server layer, user-side code would be like this:

ins, err := NewInstance() cli, err := ins.NewClient()

func NewInstance

func NewInstance(opts ...InstanceOption) (*Instance, error)

NewInstance receives InstanceOption and initializes RootConfig. There are some processing tasks during initialization.

func (*Instance) NewClient

func (ins *Instance) NewClient(opts ...client.ClientOption) (*client.Client, error)

NewClient is like client.NewClient, but inject configurations from RootConfig and ConsumerConfig

func (*Instance) NewServer

func (ins *Instance) NewServer(opts ...server.ServerOption) (*server.Server, error)

NewServer is like server.NewServer, but inject configurations from RootConfig.

type InstanceOption

type InstanceOption func(*InstanceOptions)

func WithConfigCenter

func WithConfigCenter(opts ...config_center.Option) InstanceOption

func WithEnvironment

func WithEnvironment(environment string) InstanceOption

func WithGroup

func WithGroup(group string) InstanceOption

func WithLogger

func WithLogger(opts ...logger.Option) InstanceOption

func WithMetadataReport

func WithMetadataReport(opts ...metadata.ReportOption) InstanceOption

func WithMetadataServicePort

func WithMetadataServicePort(port int) InstanceOption

func WithMetadataServiceProtocol

func WithMetadataServiceProtocol(protocol string) InstanceOption

func WithMetrics

func WithMetrics(opts ...metrics.Option) InstanceOption

func WithModule

func WithModule(module string) InstanceOption

func WithName

func WithName(name string) InstanceOption

func WithOrganization

func WithOrganization(organization string) InstanceOption

func WithOwner

func WithOwner(owner string) InstanceOption

func WithProtocol

func WithProtocol(opts ...protocol.ServerOption) InstanceOption

TODO: deal this fuction this function I want handle the protocol.Option which both server and client can use together. like:

func WithProtocol(opts ...protocol.Option) InstanceOption {
	proOpts := protocol.NewOptions(opts...)

	log.Warnf("proOpts: %+v", proOpts)

	return func(insOpts *InstanceOptions) {
		if insOpts.Protocols == nil {
			insOpts.Protocols = make(map[string]*global.ProtocolConfig)
		}
		insOpts.Protocols[proOpts.ID] = proOpts.Protocol
	}
}

but now only work in server side for compat old API.

func WithRegistry

func WithRegistry(opts ...registry.Option) InstanceOption

func WithRemoteMetadata

func WithRemoteMetadata() InstanceOption

func WithRouter

func WithRouter(opts ...router.Option) InstanceOption

func WithShutdown

func WithShutdown(opts ...graceful_shutdown.Option) InstanceOption

func WithTLS

func WithTLS(opts ...tls.Option) InstanceOption

func WithTag

func WithTag(tag string) InstanceOption

func WithTracing

func WithTracing(opts ...trace.Option) InstanceOption

WithTracing otel configuration, currently only supports tracing

func WithVersion

func WithVersion(version string) InstanceOption

type InstanceOptions

type InstanceOptions struct {
	Application    *global.ApplicationConfig         `validate:"required" yaml:"application" json:"application,omitempty" property:"application"`
	Protocols      map[string]*global.ProtocolConfig `validate:"required" yaml:"protocols" json:"protocols" property:"protocols"`
	Registries     map[string]*global.RegistryConfig `yaml:"registries" json:"registries" property:"registries"`
	ConfigCenter   *global.CenterConfig              `yaml:"config-center" json:"config-center,omitempty"`
	MetadataReport *global.MetadataReportConfig      `yaml:"metadata-report" json:"metadata-report,omitempty" property:"metadata-report"`
	Provider       *global.ProviderConfig            `yaml:"provider" json:"provider" property:"provider"`
	Consumer       *global.ConsumerConfig            `yaml:"consumer" json:"consumer" property:"consumer"`
	Metrics        *global.MetricsConfig             `yaml:"metrics" json:"metrics,omitempty" property:"metrics"`
	Otel           *global.OtelConfig                `yaml:"otel" json:"otel,omitempty" property:"otel"`
	Logger         *global.LoggerConfig              `yaml:"logger" json:"logger,omitempty" property:"logger"`
	Shutdown       *global.ShutdownConfig            `yaml:"shutdown" json:"shutdown,omitempty" property:"shutdown"`
	// todo(DMwangnima): router feature would be supported in the future
	Router              []*global.RouterConfig `yaml:"router" json:"router,omitempty" property:"router"`
	EventDispatcherType string                 `default:"direct" yaml:"event-dispatcher-type" json:"event-dispatcher-type,omitempty"`
	CacheFile           string                 `yaml:"cache_file" json:"cache_file,omitempty" property:"cache_file"`
	Custom              *global.CustomConfig   `yaml:"custom" json:"custom,omitempty" property:"custom"`
	Profiles            *global.ProfilesConfig `yaml:"profiles" json:"profiles,omitempty" property:"profiles"`
	TLSConfig           *global.TLSConfig      `yaml:"tls_config" json:"tls_config,omitempty" property:"tls_config"`
}

func (*InstanceOptions) CloneApplication

func (rc *InstanceOptions) CloneApplication() *global.ApplicationConfig

func (*InstanceOptions) CloneConfigCenter

func (rc *InstanceOptions) CloneConfigCenter() *global.CenterConfig

func (*InstanceOptions) CloneConsumer

func (rc *InstanceOptions) CloneConsumer() *global.ConsumerConfig

func (*InstanceOptions) CloneCustom

func (rc *InstanceOptions) CloneCustom() *global.CustomConfig

func (*InstanceOptions) CloneLogger

func (rc *InstanceOptions) CloneLogger() *global.LoggerConfig

func (*InstanceOptions) CloneMetadataReport

func (rc *InstanceOptions) CloneMetadataReport() *global.MetadataReportConfig

func (*InstanceOptions) CloneMetrics

func (rc *InstanceOptions) CloneMetrics() *global.MetricsConfig

func (*InstanceOptions) CloneOtel

func (rc *InstanceOptions) CloneOtel() *global.OtelConfig

func (*InstanceOptions) CloneProfiles

func (rc *InstanceOptions) CloneProfiles() *global.ProfilesConfig

func (*InstanceOptions) CloneProtocols

func (rc *InstanceOptions) CloneProtocols() map[string]*global.ProtocolConfig

func (*InstanceOptions) CloneProvider

func (rc *InstanceOptions) CloneProvider() *global.ProviderConfig

func (*InstanceOptions) CloneRegistries

func (rc *InstanceOptions) CloneRegistries() map[string]*global.RegistryConfig

func (*InstanceOptions) CloneRouter

func (rc *InstanceOptions) CloneRouter() []*global.RouterConfig

func (*InstanceOptions) CloneShutdown

func (rc *InstanceOptions) CloneShutdown() *global.ShutdownConfig

func (*InstanceOptions) CloneTLSConfig

func (rc *InstanceOptions) CloneTLSConfig() *global.TLSConfig

func (*InstanceOptions) Prefix

func (rc *InstanceOptions) Prefix() string

type LoaderConfOption

type LoaderConfOption interface {
	// contains filtered or unexported methods
}

func WithBytes

func WithBytes(bytes []byte) LoaderConfOption

WithBytes set load config bytes

func WithDelim

func WithDelim(delim string) LoaderConfOption

func WithGenre

func WithGenre(suffix string) LoaderConfOption

WithGenre set load config file suffix Deprecated: replaced by WithSuffix

func WithInstanceOptions

func WithInstanceOptions(opts *InstanceOptions) LoaderConfOption

func WithPath

func WithPath(path string) LoaderConfOption

WithPath set load config path

func WithSuffix

func WithSuffix(suffix file.Suffix) LoaderConfOption

WithSuffix set load config file suffix