guiding-dubbo-go-development

name	Guiding dubbo-go development
description	Explains dubbo-go architecture, extension points, and best practices. Use when user asks how dubbo-go works, what a concept means (filter, SPI, cluster, router, registry), which sample to look at, or asks for best practices.

Guiding dubbo-go Development

Core Concepts

Instance — top-level entry point. dubbo.NewInstance() configures the application globally. Create server and client from it.

Protocol — defines how bytes travel on the wire. Triple is recommended (HTTP/2, gRPC-compatible). Dubbo is for Java interop with Hessian2.

Registry — service discovery. Provider registers itself; consumer queries to find providers. Nacos and ZooKeeper are most common.

Filter — interceptor chain around every RPC call. Runs on both provider (server-side) and consumer (client-side). Used for auth, metrics, tracing, rate-limiting.

Cluster — fault-tolerance strategy when calling a provider group. Failover (default), Failfast, Failsafe, Forking, Broadcast.

LoadBalance — selects one provider from the list. Random (default), RoundRobin, LeastActive, ConsistentHash.

Router — filters the provider list before load balancing. Tag router, condition router, script router.

Extension Point (SPI) Pattern

All dubbo-go extensions follow the same pattern:

// 1. Implement the interface
// import "dubbo.apache.org/dubbo-go/v3/filter"
// import "dubbo.apache.org/dubbo-go/v3/protocol/base"
// import "dubbo.apache.org/dubbo-go/v3/protocol/result"
type myFilter struct{}
func (f *myFilter) Invoke(ctx context.Context, invoker base.Invoker, inv base.Invocation) result.Result {
    // before
    res := invoker.Invoke(ctx, inv)
    // after
    return res
}
func (f *myFilter) OnResponse(ctx context.Context, res result.Result, invoker base.Invoker, inv base.Invocation) result.Result {
    return res
}

// 2. Register in init()
// import "dubbo.apache.org/dubbo-go/v3/common/extension"
func init() {
    extension.SetFilter("my-filter", func() filter.Filter { return &myFilter{} })
}

// 3. Activate with blank import in main.go
// import _ "github.com/yourorg/yourapp/filter/myfilter"

// 4. Enable per-service via code API
//    srv.Register(impl, info, server.WithFilter("my-filter"))
//    or for the generated helper:
//    pb.RegisterGreetServiceHandler(srv, impl, server.WithFilter("my-filter"))

Same pattern applies to: Protocol, Registry, LoadBalancer, Router, ConfigCenter, MetadataReport.

Note: the samples repo still shows the deprecated protocol.Invoker/Invocation/Result aliases. They resolve to the same types (base.Invoker, base.Invocation, result.Result) — prefer the new packages in new code.

Samples Index

See samples-index.md for the full dubbo-go-samples directory organized by scenario.

Best Practices

• Use _ "dubbo.apache.org/dubbo-go/v3/imports" in development for convenience; switch to selective imports in production to reduce binary size.
• Always define services with Protobuf for Triple protocol — enables cross-language interop.
• Configure via the code API: dubbo.NewInstance(dubbo.WithRegistry(...), dubbo.WithProtocol(...)). YAML configs driven by dubbo.Load() still work but are the legacy path.
• Enable graceful shutdown: _ "dubbo.apache.org/dubbo-go/v3/graceful_shutdown".