dubbo-go Documentation

Technical Documentation: apache/dubbo-go

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

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 Copy Chapter

For detailed changes, refer to CHANGELOG.md.

• 3.3.2:

  BREAKING CHANGE: config package has been removed, please use modern global package, check dubbo-go-samples for usage instructions.

  Apache Dubbo-go 3.3.2 is a production-readiness release focused on API consolidation, Triple protocol capabilities, application-level metadata, service governance, concurrency safety, and release tooling. It completes the removal of the legacy config package, expands generic invocation and HTTP-facing Triple features, refreshes generated-project workflows, and fixes multiple races, stale-snapshot issues, and resource leaks.

• 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 Copy Chapter

Prerequisites Copy Section

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

Installation Copy Section

To install Dubbo-go, use the following command:

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

Quick Example Copy Section

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 Copy Chapter

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 Copy Chapter

Common development tools live in tools/.

Ecosystem Copy Chapter

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

Documentation Copy Chapter

• Official Website: https://dubbo.apache.org/
• Dubbo-go Documentation: https://cn.dubbo.apache.org/zh-cn/overview/mannual/golang-sdk/
• CHANGELOG: https://github.com/apache/dubbo-go/blob/main/CHANGELOG.md

Community Copy Chapter

• 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 Copy Chapter

Join our discussion group through Ding talk or WeChat.

[User List](https://github.com/apache/dubbo-go/issues/2) Copy Chapter

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 Copy Chapter

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

Overview (`filter/README.md`) Copy Section

Filter

Dubbo-go filters are interceptor-style extensions around RPC invocation.
They are typically used to add cross-cutting behavior such as authentication,
rate limiting, logging, tracing, metrics, generic invocation adaptation, and
graceful shutdown handling.

Getting Started Copy Chapter

The recommended approach is to import only the filters your application needs.

package demo

import _ "dubbo.apache.org/dubbo-go/v3/filter/echo"
import _ "dubbo.apache.org/dubbo-go/v3/filter/generic"

If you prefer the legacy all-in-one import, you can still use:

package demo

import _ "dubbo.apache.org/dubbo-go/v3/filter/filter_impl"

Where Filters Apply Copy Chapter

Dubbo-go distinguishes between two filter chains:

• service.filter: provider-side filters
• reference.filter: consumer-side filters

The built-in defaults are defined in common/constant/default.go.

Built-in Filters Copy Chapter

Core Copy Section

• echo: echo health check support
• generic: consumer-side generic invocation filter
• generic_service: provider-side generic service filter
• graceful_shutdown: graceful shutdown behavior for provider and consumer paths

Traffic Control Copy Section

• active: active request counting
• exec_limit: provider-side execute concurrency limiting
• tps: TPS limiting
• adaptivesvc: adaptive service filter
• polaris/limit: Polaris rate limiting
• sentinel: Sentinel integration for provider and consumer traffic protection

Security Copy Section

• token: token-based request validation
• auth: request signing and authentication
• seata: Seata distributed transaction propagation

Observability Copy Section

• accesslog: invocation access logging
• metrics: metrics collection
• tracing: tracing integration
• otel/trace: OpenTelemetry tracing integration

Extension Note Copy Section

• hystrix: moved to dubbo-go-extensions

Common Usage Copy Chapter

In practice, filters are usually enabled through application config instead of
being called directly from business code. Typical examples:

• enable a provider filter through service.filter
• enable a consumer filter through reference.filter
• import the filter package so it registers itself via extension.SetFilter(...)

Notes Copy Chapter

• Importing a filter package registers it; the filter still needs to be enabled
  by the corresponding consumer/provider configuration path when applicable.
• Some filter names differ slightly from their package directory because the
  runtime key is defined in common/constant/key.go.
• Filters under subdirectories such as otel/trace and polaris/limit are
  still ordinary Dubbo-go filters; the subdirectory just reflects feature
  grouping.

Overview (`tools/benchmark/README.md`) Copy Section

Dubbo-Go Benchmark Suite

English | 中文

Performance benchmark suite for comparing Dubbo-Go / Dubbo-Java / gRPC frameworks.

Environment Requirements Copy Chapter

• Go: 1.23+
• Java: 8+
• Maven: 3.6+
• protoc: 3.0+

Default Port Configuration Copy Chapter

Directory Structure Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Configuration Copy Chapter

Test configuration is in config.yaml, including:

• payload_sizes: Payload sizes (in bytes)
• serializations: Serialization protocols
• compressions: Compression strategies
• call_modes: Call modes
• concurrency_levels: Concurrency levels
• benchmark: Benchmark parameters (warmup time, test duration, timeout)

Code Generation Copy Chapter

After modifying proto/benchmark.proto, regenerate code:

./scripts/gen_code.sh

This script generates:

• benchmark.pb.go - Protobuf basic code
• benchmark.triple.go - Dubbo Triple protocol code
• benchmark_grpc.pb.go - gRPC protocol code

Usage Copy Chapter

Single Benchmark Copy Section

# Using script
./scripts/run_single.sh dubbo-go 1024 protobuf none 100 unary

# Or run directly
go run client/main.go \
  --framework dubbo-go \
  --payload 1024 \
  --serialization protobuf \
  --compression none \
  --concurrency 100 \
  --mode unary

Full Benchmark Copy Section

./scripts/run_all.sh

Command Line Parameters Copy Chapter

Parameter Values Copy Section

Start Server Separately Copy Chapter

# Dubbo-Go Server
cd server/dubbo-go
go run main.go --serialization protobuf --compression none --port 20000

# gRPC Server
cd server/grpc
go run main.go --port 50051

# Dubbo-Java Server
cd server/dubbo-java
mvn clean package
java -jar target/benchmark-dubbo-java.jar

Benchmark Report Copy Chapter

Test Environment Copy Section

• Go Version: 1.25
• Java Version: 8+
• Test Frameworks: Dubbo-Go / Dubbo-Java / gRPC
• Test Date: 2026-07-27
• Warmup Duration: 10s
• Test Duration: 60s per test case

Test Configuration Copy Section

128 bytes Payload Copy Section

QPS

P99 Latency (ms)

1024 bytes Payload Copy Section

QPS

P99 Latency (ms)

16384 bytes Payload Copy Section

QPS

P99 Latency (ms)

1048576 bytes Payload Copy Section

QPS

P99 Latency (ms)

Resource Usage (128B Payload, 100 Concurrency) Copy Section

Output Files Copy Chapter

Data Files Copy Section

Test results are saved in data/ directory with the naming format:

{framework}_{payload}_{serialization}_{compression}_{concurrency}_{mode}.json

JSON structure:

{
  "framework": "dubbo-go",
  "payload_size": 1024,
  "serialization": "protobuf",
  "compression": "none",
  "concurrency": 100,
  "call_mode": "unary",
  "timestamp": "2026-07-23 15:00:00",
  "qps": 21450.0,
  "success_rate": 99.99,
  "latency_p50_ms": 4.65,
  "latency_p99_ms": 5.53,
  "cpu_avg_percent": 45.2,
  "memory_peak_mb": 128.5
}

Log Files Copy Section

Logs are saved in logs/ directory, including:

• {scenario}.log - Client benchmark logs
• {scenario}.server.log - Server runtime logs

Performance Optimization Copy Chapter

Dubbo-Go Client Optimization Copy Section

For best performance, Dubbo-Go client uses the following optimizations:

Dubbo-Go Server Optimization Copy Section

Server configuration includes the following optimizations:

License Copy Chapter

Apache License 2.0

Overview (`tools/dubbo-go-schema/README.md`) Copy Section

dubbo-go-schema

English | 中文

dubbo-go-schema provides the JSON Schema used by editors and YAML language servers to validate and complete Apache dubbo-go configuration files such as dubbogo.yaml, dubbo.yaml, and application.yaml.

The schema is maintained from the current global/*_config.go YAML tags and common dubbo-go configuration examples.

Files Copy Chapter

• dubbo-go.json: JSON Schema for dubbo-go YAML configuration.
• application.yaml: example configuration that exercises common provider, consumer, Triple, metrics, tracing, logger, and shutdown settings.
• images/: screenshots used by this README.

VS Code Copy Chapter

Install a YAML language server extension, such as the Red Hat YAML extension, then add this to settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/apache/dubbo-go/develop/tools/dubbo-go-schema/dubbo-go.json": [
      "dubbo.yaml",
      "dubbogo.yaml",
      "application.yaml"
    ]
  }
}

When testing local schema changes, point VS Code at the checked-out schema file instead:

{
  "yaml.schemas": {
    "./tools/dubbo-go-schema/dubbo-go.json": [
      "dubbo.yaml",
      "dubbogo.yaml",
      "application.yaml"
    ]
  }
}

IntelliJ IDEA / GoLand Copy Chapter

Open Settings | Languages & Frameworks | Schemas and DTDs | JSON Schema Mappings, add dubbo-go.json, and map it to the config file names you use.

Validate Locally Copy Chapter

At minimum, verify that the schema is valid JSON:

node -e "JSON.parse(require('fs').readFileSync('tools/dubbo-go-schema/dubbo-go.json', 'utf8'))"

For editor validation, open application.yaml in VS Code or GoLand with the local schema mapping enabled. The schema expects dubbo-go v3 style configuration under the dubbo: root key.

Screenshots Copy Chapter

Overview (`tools/dubbogo-cli/README.md`) Copy Section

dubbogo-cli

English | 中文

dubbogo-cli is the command-line helper for the Apache dubbo-go toolchain. It can scaffold dubbo-go projects, install companion tools, inspect registry or metadata-center entries, and call Dubbo services during local debugging.

Installation Copy Chapter

go install dubbo.apache.org/dubbo-go/v3/tools/dubbogo-cli@latest

Make sure $GOPATH/bin or $(go env GOPATH)/bin is in your PATH.

Commands Copy Chapter

dubbogo-cli version
dubbogo-cli install all
dubbogo-cli install triple
dubbogo-cli install triple-openapi
dubbogo-cli install formatter
dubbogo-cli newDemo .
dubbogo-cli newApp .
dubbogo-cli show --r zookeeper --h 127.0.0.1:2181
dubbogo-cli show --mc zookeeper --h 127.0.0.1:2181
dubbogo-cli call --h localhost --p 20001 --proto dubbo --i com.example.UserProvider --method GetUser --sendObj ./request.json --recvObj ./response.json
dubbogo-cli hessian --include ./

Install Toolchain Copy Chapter

dubbogo-cli install all installs the companion tools used by current dubbo-go projects:

• protoc-gen-go-triple: generates Triple client and server bindings.
• protoc-gen-triple-openapi: generates OpenAPI v3 documents from Triple protobuf definitions.
• imports-formatter: formats Go import blocks using dubbo-go import grouping rules.

You can install a single tool with dubbogo-cli install triple, dubbogo-cli install triple-openapi, or dubbogo-cli install formatter.

Create a Demo Copy Chapter

mkdir hello-triple
cd hello-triple
dubbogo-cli newDemo .
make proto-gen
go mod tidy

Generated layout:

.
|-- Makefile
|-- api
|   `-- samples_api.proto
|-- go-client
|   `-- cmd
|       `-- client.go
|-- go-server
|   `-- cmd
|       `-- server.go
`-- go.mod

Run the server:

go run ./go-server/cmd

Run the client in another terminal:

go run ./go-client/cmd

The template keeps only protobuf source files in the scaffold. make proto-gen generates *.pb.go and *.triple.go files with protoc-gen-go and protoc-gen-go-triple.

Create an Application Copy Chapter

mkdir dubbo-go-app
cd dubbo-go-app
dubbogo-cli newApp .
make proto-gen
go mod tidy

Generated layout:

.
|-- Makefile
|-- api
|   `-- api.proto
|-- build
|   `-- Dockerfile
|-- chart
|   |-- app
|   `-- nacos_env
|-- cmd
|   `-- app.go
|-- conf
|   `-- dubbogo.yaml
|-- go.mod
`-- pkg
    `-- service
        `-- service.go

Typical workflow:

1. Edit api/api.proto.
2. Run make proto-gen.
3. Run go mod tidy.
4. Implement the service in pkg/service.
5. Update image and Helm settings in Makefile and chart/app/values.yaml.
6. Build, publish, and deploy with the provided Make targets.

Useful Make targets:

make proto-gen
make build
make buildx-publish
make deploy
make remove

Inspect Registry and Metadata Copy Chapter

Zookeeper registry:

dubbogo-cli show --r zookeeper --h 127.0.0.1:2181

Zookeeper metadata center:

dubbogo-cli show --mc zookeeper --h 127.0.0.1:2181

The command prints registered interfaces and method names. Nacos and Istio support are not implemented yet.

Debug Dubbo Protocol Services Copy Chapter

dubbogo-cli call can invoke Dubbo protocol services with request and response shapes described as JSON files.

dubbogo-cli call \
  --h localhost \
  --p 20001 \
  --proto dubbo \
  --i com.example.UserProvider \
  --method GetUser \
  --sendObj ./request.json \
  --recvObj ./response.json

Request fields use the form type@value, for example:

{
  "ID": "string@A000",
  "Male": "bool@true",
  "JavaClassName": "[email protected]"
}

Every Hessian object should provide a JavaClassName value that matches the provider-side type.

Debug Triple Services Copy Chapter

Triple services are compatible with the gRPC ecosystem. If reflection is enabled on the provider, grpc_cli can inspect and call services:

grpc_cli ls localhost:20000 -l
grpc_cli type localhost:20000 org.apache.dubbo.samples.HelloRequest
grpc_cli call localhost:20000 SayHello "name: 'laurence'"

Install grpc_cli from the gRPC project documentation.

Overview (`tools/imports-formatter/README.md`) Copy Section

imports-formatter

English | 中文

imports-formatter rewrites Go import blocks using the grouping style used by dubbo-go.

It scans a Go module, skips generated files that contain Code generated by, and groups imports into:

• Go standard library imports
• third-party imports
• current module imports

Installation Copy Chapter

go install dubbo.apache.org/dubbo-go/v3/tools/imports-formatter@latest

Make sure $(go env GOPATH)/bin is in your PATH.

You can also install it through dubbogo-cli:

dubbogo-cli install formatter

Usage Copy Chapter

Format the current module:

imports-formatter

Format a specific module path:

imports-formatter --path /path/to/module

Pass the module path explicitly when the target directory does not contain go.mod:

imports-formatter --path /path/to/module/subdir --module dubbo.apache.org/dubbo-go/v3

Disable blank lines between third-party import groups:

imports-formatter --bl=false

Flags Copy Chapter

Notes Copy Chapter

imports-formatter edits files in place. Review the diff before committing.

Overview (`tools/protoc-gen-go-triple/README.md`) Copy Section

protoc-gen-go-triple

English | 中文

protoc-gen-go-triple is the protobuf compiler plugin that generates dubbo-go Triple client and server bindings.

It works together with protoc-gen-go: protoc-gen-go generates protobuf message types, and protoc-gen-go-triple generates Triple service interfaces, clients, handlers, and registration helpers.

Requirements Copy Chapter

• Go 1.23 or later
• protoc
• protoc-gen-go

Install protoc-gen-go if it is not already available:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

Installation Copy Chapter

go install dubbo.apache.org/dubbo-go/v3/tools/protoc-gen-go-triple@latest

Make sure $(go env GOPATH)/bin is in your PATH.

Usage Copy Chapter

protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-triple_out=. \
  --go-triple_opt=paths=source_relative \
  ./api/greet.proto

For greet.proto, the generated files are:

• greet.pb.go: protobuf messages generated by protoc-gen-go
• greet.triple.go: Triple bindings generated by protoc-gen-go-triple

Proto Example Copy Chapter

syntax = "proto3";

package greet;

option go_package = "example.com/hello/api;api";

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

The protobuf package controls the Triple service name exposed on the wire. The go_package option controls the Go import path and package name for generated files.

Generated API Copy Chapter

Current generated code uses the dubbo-go v3 Triple API:

greeter, err := api.NewGreetService(cli)

err := api.RegisterGreetServiceHandler(srv, &GreetServiceImpl{})

The generated file suffix is .triple.go.

Legacy Compatibility Copy Chapter

For dubbo-go 3.2.0 and later, use the default generator output.

To generate stubs compatible with older dubbo-go releases, pass useOldVersion=true:

protoc \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-triple_out=. \
  --go-triple_opt=paths=source_relative,useOldVersion=true \
  ./api/greet.proto

The old compatibility mode is retained for migration only. New projects should use the default output.

Overview (`tools/protoc-gen-triple-openapi/README.md`) Copy Section

protoc-gen-triple-openapi

English | 中文

protoc-gen-triple-openapi is a protoc plugin that generates OpenAPI v3 documents from protobuf services used with the Dubbo Triple protocol.

Requirements Copy Chapter

• Go 1.23 or later
• protoc
• protobuf files that define Triple services

Installation Copy Chapter

go install dubbo.apache.org/dubbo-go/v3/tools/protoc-gen-triple-openapi@latest

Make sure $(go env GOPATH)/bin is in your PATH.

Usage Copy Chapter

Generate YAML, the default format:

protoc \
  --triple-openapi_out=. \
  --triple-openapi_opt=format=yaml \
  ./api/greet.proto

Generate JSON:

protoc \
  --triple-openapi_out=. \
  --triple-openapi_opt=format=json \
  ./api/greet.proto

Generated file names use the input proto base name:

• greet.triple.openapi.yaml
• greet.triple.openapi.json

Proto Example Copy Chapter

syntax = "proto3";

package org.apache.dubbo.samples.greet;

option go_package = "example.com/hello/api;api";

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}

Options Copy Chapter

Version Copy Chapter

protoc-gen-triple-openapi --version

Overview (`protocol/grpc/internal/README.md`) Copy Section

internal

This internal package is for test. So don't use internal in production.

require Copy Chapter

• protoc
• protoc-gen-go: github.com/golang/protobuf/[email protected]

usage Copy Chapter

• helloworld: test unary process
• routeguide: test stream process
• multiprotos: use multi pb to generate multi pb.go

--- METRICS ---

• Files Extracted: 9
• Estimated Token Budget: ~7954 tokens
• Canonical Reference: https://codewiki.google/github.com/apache/dubbo-go