This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/dubbo-go.git
The following commit(s) were added to refs/heads/develop by this push:
new 77cef1a51 docs(metadata): complete metadata option comments and unit
test coverage (#3657)
77cef1a51 is described below
commit 77cef1a512f9edde2607c4b48136ccf1f1099650
Author: MaoMeng <[email protected]>
AuthorDate: Sat Aug 15 23:45:49 2026 +0800
docs(metadata): complete metadata option comments and unit test coverage
(#3657)
* docs(metadata): complete metadata option comments and unit test coverage
* docs(metadata): refine WithMetadataType/WithMetadataProtocol/WithProtocol
comments
---
metadata/options.go | 44 +++++++++-
metadata/options_test.go | 217 +++++++++++++++++++++++++++++++++++------------
2 files changed, 205 insertions(+), 56 deletions(-)
diff --git a/metadata/options.go b/metadata/options.go
index 483ed2f04..9b3a63515 100644
--- a/metadata/options.go
+++ b/metadata/options.go
@@ -41,17 +41,24 @@ var (
exportOnce sync.Once
)
+// Options holds the configuration for the metadata service.
type Options struct {
- appName string
+ // appName is the application name.
+ appName string
+ // metadataType is the metadata storage type (local or remote), default
value is local.
metadataType string
- port int
- protocol string
+ // port is the metadata service listen port, 0 means a random port is
used.
+ port int
+ // protocol is the protocol used to export the MetadataService, default
value is dubbo.
+ protocol string
}
+// defaultOptions returns a default Options instance.
func defaultOptions() *Options {
return &Options{metadataType: constant.DefaultMetadataStorageType,
protocol: constant.DefaultProtocol}
}
+// NewOptions returns an Options instance from given options.
func NewOptions(opts ...Option) *Options {
metaOptions := defaultOptions()
for _, opt := range opts {
@@ -60,6 +67,8 @@ func NewOptions(opts ...Option) *Options {
return metaOptions
}
+// Init registers opts as the global metadata options and, for local storage,
+// exports the metadata service only once.
func (opts *Options) Init() error {
metadataOptions = opts
var err error
@@ -80,37 +89,50 @@ func (opts *Options) Init() error {
return err
}
+// Option configures an Options instance.
type Option func(*Options)
+// WithAppName sets the application owning the metadata service.
func WithAppName(app string) Option {
return func(options *Options) {
options.appName = app
}
}
+// WithMetadataType sets the metadata storage type,
+// allowed values are "local" and "remote",
+// any other value behaves as "local".
func WithMetadataType(typ string) Option {
return func(options *Options) {
options.metadataType = typ
}
}
+// WithPort sets the metadata service listen port.
func WithPort(port int) Option {
return func(options *Options) {
options.port = port
}
}
+// WithMetadataProtocol sets the protocol used to export the MetadataService,
+// allowed values are "dubbo" and "tri",
+// any other value behaves as "tri".
func WithMetadataProtocol(protocol string) Option {
return func(options *Options) {
options.protocol = protocol
}
}
+// ReportOptions holds the configuration for a metadata report center
connection.
type ReportOptions struct {
+ // registryId is used as a key to look up the report instance.
registryId string
+ // MetadataReportConfig embeds the connection configuration.
*global.MetadataReportConfig
}
+// InitRegistryMetadataReport initializes a metadata report for each registry
func InitRegistryMetadataReport(registries map[string]*global.RegistryConfig)
error {
if len(registries) > 0 {
for id, reg := range registries {
@@ -151,6 +173,7 @@ func fromRegistry(id string, rc *global.RegistryConfig)
*ReportOptions {
return opts
}
+// Init builds a report URL from opts and registers the metadata report under
opts.registryId.
func (opts *ReportOptions) Init() error {
url, err := opts.toUrl()
if err != nil {
@@ -181,10 +204,12 @@ func (opts *ReportOptions) toUrl() (*common.URL, error) {
return res, nil
}
+// defaultReportOptions returns a default ReportOptions instance.
func defaultReportOptions() *ReportOptions {
return &ReportOptions{MetadataReportConfig:
global.DefaultMetadataReportConfig()}
}
+// NewReportOptions returns a ReportOptions instance from given options.
func NewReportOptions(opts ...ReportOption) *ReportOptions {
reportOptions := defaultReportOptions()
for _, opt := range opts {
@@ -193,26 +218,32 @@ func NewReportOptions(opts ...ReportOption)
*ReportOptions {
return reportOptions
}
+// ReportOption configures a ReportOptions instance.
type ReportOption func(*ReportOptions)
+// WithZookeeper sets the metadata report protocol to zookeeper.
func WithZookeeper() ReportOption {
return func(opts *ReportOptions) {
opts.Protocol = constant.ZookeeperKey
}
}
+// WithNacos sets the metadata report protocol to nacos.
func WithNacos() ReportOption {
return func(opts *ReportOptions) {
opts.Protocol = constant.NacosKey
}
}
+// WithEtcdV3 sets the metadata report protocol to etcd v3.
func WithEtcdV3() ReportOption {
return func(opts *ReportOptions) {
opts.Protocol = constant.EtcdV3Key
}
}
+// WithProtocol sets the metadata report protocol to a custom value.
+// For the built-in backends, use WithZookeeper, WithNacos, or WithEtcdV3.
func WithProtocol(meta string) ReportOption {
return func(opts *ReportOptions) {
opts.Protocol = meta
@@ -230,42 +261,49 @@ func WithAddress(address string) ReportOption {
}
}
+// WithUsername sets the metadata report username. Consumed only by nacos.
func WithUsername(username string) ReportOption {
return func(opts *ReportOptions) {
opts.Username = username
}
}
+// WithPassword sets the metadata report password. Consumed only by nacos.
func WithPassword(password string) ReportOption {
return func(opts *ReportOptions) {
opts.Password = password
}
}
+// WithTimeout sets the metadata report timeout.
func WithTimeout(timeout time.Duration) ReportOption {
return func(opts *ReportOptions) {
opts.Timeout = strconv.Itoa(int(timeout.Milliseconds()))
}
}
+// WithGroup sets the isolation group.
func WithGroup(group string) ReportOption {
return func(opts *ReportOptions) {
opts.Group = group
}
}
+// WithNamespace sets the metadata report namespace. Consumed only by nacos.
func WithNamespace(namespace string) ReportOption {
return func(opts *ReportOptions) {
opts.Namespace = namespace
}
}
+// WithParams sets extra params passed through to the backend client library.
func WithParams(params map[string]string) ReportOption {
return func(opts *ReportOptions) {
opts.Params = params
}
}
+// WithRegistryId sets the registry id this report originates from.
func WithRegistryId(id string) ReportOption {
return func(opts *ReportOptions) {
opts.registryId = id
diff --git a/metadata/options_test.go b/metadata/options_test.go
index a1ececf8c..7fe741533 100644
--- a/metadata/options_test.go
+++ b/metadata/options_test.go
@@ -33,65 +33,170 @@ import (
)
func TestNewOptions(t *testing.T) {
- // Test default options
- opts := NewOptions()
- assert.Equal(t, constant.DefaultMetadataStorageType, opts.metadataType)
- assert.Equal(t, constant.DefaultProtocol, opts.protocol)
-
- // Test with all options
- opts = NewOptions(
- WithAppName("my-app"),
- WithMetadataType("remote"),
- WithPort(20880),
- WithMetadataProtocol("tri"),
- )
- assert.Equal(t, "my-app", opts.appName)
- assert.Equal(t, "remote", opts.metadataType)
- assert.Equal(t, 20880, opts.port)
- assert.Equal(t, "tri", opts.protocol)
+ tests := []struct {
+ name string
+ opts []Option
+ wantApp string
+ wantType string
+ wantPort int
+ wantProto string
+ }{
+ {
+ name: "default",
+ opts: nil,
+ wantApp: "",
+ wantType: constant.DefaultMetadataStorageType,
+ wantPort: 0,
+ wantProto: constant.DefaultProtocol,
+ },
+ {
+ name: "with-app",
+ opts: []Option{WithAppName("my-app")},
+ wantApp: "my-app",
+ wantType: constant.DefaultMetadataStorageType,
+ wantPort: 0,
+ wantProto: constant.DefaultProtocol,
+ },
+ {
+ name: "with-type",
+ opts: []Option{WithMetadataType("remote")},
+ wantApp: "",
+ wantType: "remote",
+ wantPort: 0,
+ wantProto: constant.DefaultProtocol,
+ },
+ {
+ name: "with-port",
+ opts: []Option{WithPort(20880)},
+ wantApp: "",
+ wantType: constant.DefaultMetadataStorageType,
+ wantPort: 20880,
+ wantProto: constant.DefaultProtocol,
+ },
+ {
+ name: "with-protocol",
+ opts: []Option{WithMetadataProtocol("tri")},
+ wantApp: "",
+ wantType: constant.DefaultMetadataStorageType,
+ wantPort: 0,
+ wantProto: "tri",
+ },
+ {
+ name: "all-set",
+ opts: []Option{
+ WithAppName("my-app"),
+ WithMetadataType("remote"),
+ WithPort(20880),
+ WithMetadataProtocol("tri"),
+ },
+ wantApp: "my-app",
+ wantType: "remote",
+ wantPort: 20880,
+ wantProto: "tri",
+ },
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ opts := NewOptions(tt.opts...)
+ assert.Equal(t, tt.wantApp, opts.appName)
+ assert.Equal(t, tt.wantType, opts.metadataType)
+ assert.Equal(t, tt.wantPort, opts.port)
+ assert.Equal(t, tt.wantProto, opts.protocol)
+ })
+ }
}
func TestNewReportOptions(t *testing.T) {
- // Test default
- opts := NewReportOptions()
- assert.NotNil(t, opts.MetadataReportConfig)
-
- // Test with all options
- opts = NewReportOptions(
- WithRegistryId("registry-1"),
- WithZookeeper(),
- WithAddress("127.0.0.1:2181"),
- WithUsername("admin"),
- WithPassword("secret"),
- WithTimeout(5*time.Second),
- WithGroup("test-group"),
- WithNamespace("test-ns"),
- WithParams(map[string]string{"key": "value"}),
- )
- assert.Equal(t, "registry-1", opts.registryId)
- assert.Equal(t, constant.ZookeeperKey, opts.Protocol)
- assert.Equal(t, "127.0.0.1:2181", opts.Address)
- assert.Equal(t, "admin", opts.Username)
- assert.Equal(t, "secret", opts.Password)
- assert.Equal(t, "5000", opts.Timeout)
- assert.Equal(t, "test-group", opts.Group)
- assert.Equal(t, "test-ns", opts.Namespace)
- assert.Equal(t, "value", opts.Params["key"])
-}
-
-func TestProtocolOptions(t *testing.T) {
tests := []struct {
- option ReportOption
- expected string
+ name string
+ opts []ReportOption
+ get func(*ReportOptions) string
+ want string
}{
- {WithZookeeper(), constant.ZookeeperKey},
- {WithNacos(), constant.NacosKey},
- {WithEtcdV3(), constant.EtcdV3Key},
+ {
+ name: "default",
+ opts: nil,
+ get: func(o *ReportOptions) string { return o.Protocol
},
+ want: "",
+ },
+ {
+ name: "with-registryId",
+ opts: []ReportOption{WithRegistryId("registry-1")},
+ get: func(o *ReportOptions) string { return
o.registryId },
+ want: "registry-1",
+ },
+ {
+ name: "with-zookeeper",
+ opts: []ReportOption{WithZookeeper()},
+ get: func(o *ReportOptions) string { return o.Protocol
},
+ want: constant.ZookeeperKey,
+ },
+ {
+ name: "with-nacos",
+ opts: []ReportOption{WithNacos()},
+ get: func(o *ReportOptions) string { return o.Protocol
},
+ want: constant.NacosKey,
+ },
+ {
+ name: "with-etcdv3",
+ opts: []ReportOption{WithEtcdV3()},
+ get: func(o *ReportOptions) string { return o.Protocol
},
+ want: constant.EtcdV3Key,
+ },
+ {
+ name: "with-protocol-generic",
+ opts: []ReportOption{WithProtocol("consul")},
+ get: func(o *ReportOptions) string { return o.Protocol
},
+ want: "consul",
+ },
+ {
+ name: "with-address",
+ opts: []ReportOption{WithAddress("127.0.0.1:2181")},
+ get: func(o *ReportOptions) string { return o.Address
},
+ want: "127.0.0.1:2181",
+ },
+ {
+ name: "with-username",
+ opts: []ReportOption{WithUsername("admin")},
+ get: func(o *ReportOptions) string { return o.Username
},
+ want: "admin",
+ },
+ {
+ name: "with-password",
+ opts: []ReportOption{WithPassword("secret")},
+ get: func(o *ReportOptions) string { return o.Password
},
+ want: "secret",
+ },
+ {
+ name: "with-timeout",
+ opts: []ReportOption{WithTimeout(5 * time.Second)},
+ get: func(o *ReportOptions) string { return o.Timeout
},
+ want: "5000",
+ },
+ {
+ name: "with-group",
+ opts: []ReportOption{WithGroup("test-group")},
+ get: func(o *ReportOptions) string { return o.Group },
+ want: "test-group",
+ },
+ {
+ name: "with-namespace",
+ opts: []ReportOption{WithNamespace("test-ns")},
+ get: func(o *ReportOptions) string { return
o.Namespace },
+ want: "test-ns",
+ },
+ {
+ name: "with-params",
+ opts:
[]ReportOption{WithParams(map[string]string{"key": "value"})},
+ get: func(o *ReportOptions) string { return
o.Params["key"] },
+ want: "value",
+ },
}
for _, tt := range tests {
- opts := defaultReportOptions()
- tt.option(opts)
- assert.Equal(t, tt.expected, opts.Protocol)
+ t.Run(tt.name, func(t *testing.T) {
+ o := NewReportOptions(tt.opts...)
+ assert.Equal(t, tt.want, tt.get(o))
+ })
}
}
@@ -112,10 +217,16 @@ func TestWithAddressProtocolParsing(t *testing.T) {
func TestReportOptionsToUrl(t *testing.T) {
// Valid options
- opts := NewReportOptions(WithZookeeper(), WithAddress("127.0.0.1:2181"))
+ opts := NewReportOptions(
+ WithZookeeper(),
+ WithAddress("127.0.0.1:2181"),
+ WithParams(map[string]string{"key": "value"}),
+ )
url, err := opts.toUrl()
require.NoError(t, err)
assert.Equal(t, "zookeeper", url.Protocol)
+ assert.Equal(t, "zookeeper", url.GetParam("metadata", ""))
+ assert.Equal(t, "value", url.GetParam("key", ""))
// Invalid options - empty protocol
opts = NewReportOptions(WithAddress("127.0.0.1:2181"))
