migrating-to-dubbo-go

name	Migrating to dubbo-go
description	Guides migration to dubbo-go from gRPC-Go, Spring Cloud, or plain HTTP/Gin. Use when user asks how to migrate from another framework, port existing services to dubbo-go, or upgrade dubbo-go from v1/v2 to v3.

Migrating to dubbo-go

First question: Where are you migrating from?

• A) gRPC-Go
• B) Spring Cloud (Java)
• C) Gin / plain HTTP
• D) dubbo-go v1 or v2 → v3

---

From gRPC-Go

Concept mapping

gRPC-Go	dubbo-go
grpc.NewServer()	server.NewServer() (or ins.NewServer() when using dubbo.NewInstance)
pb.RegisterXxxServer(srv, impl)	pb.RegisterXxxHandler(srv, impl) (Triple)
grpc.Dial(addr)	client.NewClient() → pb.NewXxxService(cli)
Interceptor (UnaryServerInterceptor)	Filter
grpc.WithUnaryInterceptor(...)	server.WithFilter("my-filter") + blank import
Service reflection	Built-in with Triple

Proto file: No changes needed. Triple is wire-compatible with gRPC.

Key difference: dubbo-go adds service discovery (registry) on top of gRPC. If you want direct connection, use direct mode — no registry needed.

// gRPC-Go before
conn, _ := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
client := pb.NewGreetClient(conn)

// dubbo-go after (direct mode)
cli, _ := client.NewClient(
    client.WithClientURL("127.0.0.1:20000"), // or "tri://127.0.0.1:20000"
)
svc, _ := pb.NewGreetService(cli)

See dubbo-go-samples/rpc/grpc and dubbo-go-samples/direct

---

From Spring Cloud (Java)

Concept mapping

Spring Cloud	dubbo-go
@EnableDiscoveryClient	dubbo.WithRegistry(registry.WithNacos(), registry.WithAddress(...))
@FeignClient	client.NewClient() + generated pb.NewXxxService(cli)
@RestController	pb.RegisterXxxHandler(srv, impl) + Triple/REST protocol
Spring Cloud Gateway	Apache APISIX or direct
Hystrix / Resilience4j	Hystrix filter / Sentinel filter
Sleuth / Zipkin	OpenTelemetry filter
Actuator /health	metrics/probe (/live, /ready)

Migration path:

1. Keep Java services running
2. Add dubbo-go provider for new Go services using Triple + Protobuf
3. Java consumers can call Go providers via Triple (wire-compatible)
4. Migrate Java consumers to Go one by one

See dubbo-go-samples/java_interop

---

From Gin / plain HTTP

Concept mapping

Gin / HTTP	dubbo-go
gin.Default() + r.POST(...)	server.NewServer() + pb.RegisterXxxHandler(...) (Triple)
http.Get(url) / http.Client	client.NewClient() + pb.NewXxxService(cli)
Gin middleware	Filter (see filter/custom)
r.Run(":8080")	srv.Serve()
Route handler func	Service implementation struct method

dubbo-go is an RPC framework, not an HTTP framework. Typical approach:

Option A — Keep Gin for HTTP, add dubbo-go for internal RPC

• Gin handles external HTTP API
• dubbo-go handles service-to-service communication
• No conflict; run both in same process

Option B — Use Triple REST mode Triple supports HTTP/1.1 REST endpoints. Define proto, get both RPC and REST.

import "google/api/annotations.proto";

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {
    option (google.api.http) = { post: "/greet" body: "*" };
  }
}

See rpc/triple/openapi

---

From dubbo-go v1/v2 → v3

Breaking changes summary

v1/v2	v3
config.Load()	dubbo.NewInstance() (code API, recommended) or dubbo.Load() (YAML-driven, legacy)
hessian.RegisterPOJO() + interface-based	Protobuf + generated code (recommended)
config.SetProviderService()	pb.RegisterGreetServiceHandler(srv, impl)
config.ConsumerConfig.References	client.NewClient() → pb.NewXxxService(cli)
getty as default transport	Triple as default protocol

Recommended: migrate to the code API (dubbo.NewInstance(dubbo.WithRegistry(...), dubbo.WithProtocol(...))). YAML-driven configuration still works via dubbo.Load(), but YAML key structure is not guaranteed to be identical across v1/v2/v3 — expect to rewrite registries, protocols, and service registration.

See the dubbo-go v3 user manual (English) or 中文版