diff --git a/README.md b/README.md index 74cff65b..0526e3b5 100644 --- a/README.md +++ b/README.md @@ -9,50 +9,54 @@ Nacos-sdk-go for Go client allows you to access Nacos service,it supports service discovery and dynamic configuration. ## Requirements + Supported Go version over 1.14 Supported Nacos version over 2.x ## Installation + Use `go get` to install SDK： + ```sh -$ go get -u github.com/nacos-group/nacos-sdk-go +$ go get -u github.com/nacos-group/nacos-sdk-go/v2 ``` + ## Quick Examples + * ClientConfig ```go constant.ClientConfig{ - TimeoutMs uint64 // timeout for requesting Nacos server, default value is 10000ms - NamespaceId string // the namespaceId of Nacos - Endpoint string // the endpoint for ACM. https://help.aliyun.com/document_detail/130146.html - RegionId string // the regionId for ACM & KMS - AccessKey string // the AccessKey for ACM & KMS - SecretKey string // the SecretKey for ACM & KMS - OpenKMS bool // it's to open KMS, default is false. https://help.aliyun.com/product/28933.html - // , to enable encrypt/decrypt, DataId should be start with "cipher-" - CacheDir string // the directory for persist nacos service info,default value is current path - UpdateThreadNum int // the number of goroutine for update nacos service info,default value is 20 - NotLoadCacheAtStart bool // not to load persistent nacos service info in CacheDir at start time - UpdateCacheWhenEmpty bool // update cache when get empty service instance from server - Username string // the username for nacos auth - Password string // the password for nacos auth - LogDir string // the directory for log, default is current path - RotateTime string // the rotate time for log, eg: 30m, 1h, 24h, default is 24h - MaxAge int64 // the max age of a log file, default value is 3 - LogLevel string // the level of log, it's must be debug,info,warn,error, default value is info +TimeoutMs uint64 // timeout for requesting Nacos server, default value is 10000ms +NamespaceId string // the namespaceId of Nacos +Endpoint string // the endpoint for ACM. https://help.aliyun.com/document_detail/130146.html +RegionId string // the regionId for ACM & KMS +AccessKey string // the AccessKey for ACM & KMS +SecretKey string // the SecretKey for ACM & KMS +OpenKMS bool // it's to open KMS, default is false. https://help.aliyun.com/product/28933.html +// , to enable encrypt/decrypt, DataId should be start with "cipher-" +CacheDir string // the directory for persist nacos service info,default value is current path +UpdateThreadNum int // the number of goroutine for update nacos service info,default value is 20 +NotLoadCacheAtStart bool // not to load persistent nacos service info in CacheDir at start time +UpdateCacheWhenEmpty bool // update cache when get empty service instance from server +Username string // the username for nacos auth +Password string // the password for nacos auth +LogDir string // the directory for log, default is current path +RotateTime string // the rotate time for log, eg: 30m, 1h, 24h, default is 24h +MaxAge int64 // the max age of a log file, default value is 3 +LogLevel string // the level of log, it's must be debug,info,warn,error, default value is info } ``` - * ServerConfig ```go constant.ServerConfig{ - ContextPath string // the nacos server context path - IpAddr string // the nacos server address - Port uint64 // the nacos server port - Scheme string // the nacos server scheme +Scheme string // the nacos server scheme,defaut=http,this is not required in 2.0 +ContextPath string // the nacos server contextpath,defaut=/nacos,this is not required in 2.0 +IpAddr string // the nacos server address +Port uint64 // nacos server port } ``` @@ -63,112 +67,108 @@ constant.ServerConfig{ ```go //create clientConfig clientConfig := constant.ClientConfig{ - NamespaceId: "e525eafa-f7d7-4029-83d9-008937f9d468", //we can create multiple clients with different namespaceId to support multiple namespace.When namespace is public, fill in the blank string here. - TimeoutMs: 5000, - NotLoadCacheAtStart: true, - LogDir: "/tmp/nacos/log", - CacheDir: "/tmp/nacos/cache", - RotateTime: "1h", - MaxAge: 3, - LogLevel: "debug", +NamespaceId: "e525eafa-f7d7-4029-83d9-008937f9d468", //we can create multiple clients with different namespaceId to support multiple namespace.When namespace is public, fill in the blank string here. +TimeoutMs: 5000, +NotLoadCacheAtStart: true, +LogDir: "/tmp/nacos/log", +CacheDir: "/tmp/nacos/cache", +LogLevel: "debug", } //Another way of create clientConfig clientConfig := *constant.NewClientConfig( - constant.WithNamespaceId("e525eafa-f7d7-4029-83d9-008937f9d468"), //When namespace is public, fill in the blank string here. - constant.WithTimeoutMs(5000), - constant.WithNotLoadCacheAtStart(true), - constant.WithLogDir("/tmp/nacos/log"), - constant.WithCacheDir("/tmp/nacos/cache"), - constant.WithRotateTime("1h"), - constant.WithMaxAge(3), - constant.WithLogLevel("debug"), +constant.WithNamespaceId("e525eafa-f7d7-4029-83d9-008937f9d468"), //When namespace is public, fill in the blank string here. +constant.WithTimeoutMs(5000), +constant.WithNotLoadCacheAtStart(true), +constant.WithLogDir("/tmp/nacos/log"), +constant.WithCacheDir("/tmp/nacos/cache"), +constant.WithLogLevel("debug"), ) // At least one ServerConfig serverConfigs := []constant.ServerConfig{ - { - IpAddr: "console1.nacos.io", - ContextPath: "/nacos", - Port: 80, - Scheme: "http", - }, - { - IpAddr: "console2.nacos.io", - ContextPath: "/nacos", - Port: 80, - Scheme: "http", - }, +{ +IpAddr: "console1.nacos.io", +ContextPath: "/nacos", +Port: 80, +Scheme: "http", +}, +{ +IpAddr: "console2.nacos.io", +ContextPath: "/nacos", +Port: 80, +Scheme: "http", +}, } //Another way of create serverConfigs serverConfigs := []constant.ServerConfig{ - *constant.NewServerConfig( - "console1.nacos.io", - 80, - constant.WithScheme("http"), - constant.WithContextPath("/nacos") - ), - *constant.NewServerConfig( - "console2.nacos.io", - 80, - constant.WithScheme("http"), - constant.WithContextPath("/nacos") - ), +*constant.NewServerConfig( +"console1.nacos.io", +80, +constant.WithScheme("http"), +constant.WithContextPath("/nacos") +), +*constant.NewServerConfig( +"console2.nacos.io", +80, +constant.WithScheme("http"), +constant.WithContextPath("/nacos") +), } // Create naming client for service discovery _, _ := clients.CreateNamingClient(map[string]interface{}{ - "serverConfigs": serverConfigs, - "clientConfig": clientConfig, +"serverConfigs": serverConfigs, +"clientConfig": clientConfig, }) // Create config client for dynamic configuration _, _ := clients.CreateConfigClient(map[string]interface{}{ - "serverConfigs": serverConfigs, - "clientConfig": clientConfig, +"serverConfigs": serverConfigs, +"clientConfig": clientConfig, }) // Another way of create naming client for service discovery (recommend) namingClient, err := clients.NewNamingClient( - vo.NacosClientParam{ - ClientConfig: &clientConfig, - ServerConfigs: serverConfigs, - }, +vo.NacosClientParam{ +ClientConfig: &clientConfig, +ServerConfigs: serverConfigs, +}, ) // Another way of create config client for dynamic configuration (recommend) configClient, err := clients.NewConfigClient( - vo.NacosClientParam{ - ClientConfig: &clientConfig, - ServerConfigs: serverConfigs, - }, +vo.NacosClientParam{ +ClientConfig: &clientConfig, +ServerConfigs: serverConfigs, +}, ) ``` ### Create client for ACM + https://help.aliyun.com/document_detail/130146.html ```go cc := constant.ClientConfig{ - Endpoint: "acm.aliyun.com:8080", - NamespaceId: "e525eafa-f7d7-4029-83d9-008937f9d468", - RegionId: "cn-shanghai", - AccessKey: "LTAI4G8KxxxxxxxxxxxxxbwZLBr", - SecretKey: "n5jTL9YxxxxxxxxxxxxaxmPLZV9", - OpenKMS: true, - TimeoutMs: 5000, - LogLevel: "debug", +Endpoint: "acm.aliyun.com:8080", +NamespaceId: "e525eafa-f7d7-4029-83d9-008937f9d468", +RegionId: "cn-shanghai", +AccessKey: "LTAI4G8KxxxxxxxxxxxxxbwZLBr", +SecretKey: "n5jTL9YxxxxxxxxxxxxaxmPLZV9", +OpenKMS: true, +TimeoutMs: 5000, +LogLevel: "debug", } // a more graceful way to create config client client, err := clients.NewConfigClient( - vo.NacosClientParam{ - ClientConfig: &cc, - }, +vo.NacosClientParam{ +ClientConfig: &cc, +}, ) ``` - ### Service Discovery * Register instance：RegisterInstance @@ -176,16 +176,16 @@ client, err := clients.NewConfigClient( ```go success, err := namingClient.RegisterInstance(vo.RegisterInstanceParam{ - Ip: "10.0.0.11", - Port: 8848, - ServiceName: "demo.go", - Weight: 10, - Enable: true, - Healthy: true, - Ephemeral: true, - Metadata: map[string]string{"idc":"shanghai"}, - ClusterName: "cluster-a", // default value is DEFAULT - GroupName: "group-a", // default value is DEFAULT_GROUP +Ip: "10.0.0.11", +Port: 8848, +ServiceName: "demo.go", +Weight: 10, +Enable: true, +Healthy: true, +Ephemeral: true, +Metadata: map[string]string{"idc":"shanghai"}, +ClusterName: "cluster-a", // default value is DEFAULT +GroupName: "group-a", // default value is DEFAULT_GROUP }) ``` @@ -195,12 +195,12 @@ success, err := namingClient.RegisterInstance(vo.RegisterInstanceParam{ ```go success, err := namingClient.DeregisterInstance(vo.DeregisterInstanceParam{ - Ip: "10.0.0.11", - Port: 8848, - ServiceName: "demo.go", - Ephemeral: true, - Cluster: "cluster-a", // default value is DEFAULT - GroupName: "group-a", // default value is DEFAULT_GROUP +Ip: "10.0.0.11", +Port: 8848, +ServiceName: "demo.go", +Ephemeral: true, +Cluster: "cluster-a", // default value is DEFAULT +GroupName: "group-a", // default value is DEFAULT_GROUP }) ``` @@ -210,9 +210,9 @@ success, err := namingClient.DeregisterInstance(vo.DeregisterInstanceParam{ ```go services, err := namingClient.GetService(vo.GetServiceParam{ - ServiceName: "demo.go", - Clusters: []string{"cluster-a"}, // default value is DEFAULT - GroupName: "group-a", // default value is DEFAULT_GROUP +ServiceName: "demo.go", +Clusters: []string{"cluster-a"}, // default value is DEFAULT +GroupName: "group-a", // default value is DEFAULT_GROUP }) ``` @@ -222,9 +222,9 @@ services, err := namingClient.GetService(vo.GetServiceParam{ ```go // SelectAllInstance return all instances,include healthy=false,enable=false,weight<=0 instances, err := namingClient.SelectAllInstances(vo.SelectAllInstancesParam{ - ServiceName: "demo.go", - GroupName: "group-a", // default value is DEFAULT_GROUP - Clusters: []string{"cluster-a"}, // default value is DEFAULT +ServiceName: "demo.go", +GroupName: "group-a", // default value is DEFAULT_GROUP +Clusters: []string{"cluster-a"}, // default value is DEFAULT }) ``` @@ -234,10 +234,10 @@ instances, err := namingClient.SelectAllInstances(vo.SelectAllInstancesParam{ ```go // SelectInstances only return the instances of healthy=${HealthyOnly},enable=true and weight>0 instances, err := namingClient.SelectInstances(vo.SelectInstancesParam{ - ServiceName: "demo.go", - GroupName: "group-a", // default value is DEFAULT_GROUP - Clusters: []string{"cluster-a"}, // default value is DEFAULT - HealthyOnly: true, +ServiceName: "demo.go", +GroupName: "group-a", // default value is DEFAULT_GROUP +Clusters: []string{"cluster-a"}, // default value is DEFAULT +HealthyOnly: true, }) ``` @@ -248,9 +248,9 @@ instances, err := namingClient.SelectInstances(vo.SelectInstancesParam{ // SelectOneHealthyInstance return one instance by WRR strategy for load balance // And the instance should be health=true,enable=true and weight>0 instance, err := namingClient.SelectOneHealthyInstance(vo.SelectOneHealthInstanceParam{ - ServiceName: "demo.go", - GroupName: "group-a", // default value is DEFAULT_GROUP - Clusters: []string{"cluster-a"}, // default value is DEFAULT +ServiceName: "demo.go", +GroupName: "group-a", // default value is DEFAULT_GROUP +Clusters: []string{"cluster-a"}, // default value is DEFAULT }) ``` @@ -262,12 +262,12 @@ instance, err := namingClient.SelectOneHealthyInstance(vo.SelectOneHealthInstanc // Subscribe key = serviceName+groupName+cluster // Note: We call add multiple SubscribeCallback with the same key. err := namingClient.Subscribe(vo.SubscribeParam{ - ServiceName: "demo.go", - GroupName: "group-a", // default value is DEFAULT_GROUP - Clusters: []string{"cluster-a"}, // default value is DEFAULT - SubscribeCallback: func(services []model.Instance, err error) { - log.Printf("\n\n callback return services:%s \n\n", utils.ToJsonString(services)) - }, +ServiceName: "demo.go", +GroupName: "group-a", // default value is DEFAULT_GROUP +Clusters: []string{"cluster-a"}, // default value is DEFAULT +SubscribeCallback: func (services []model.Instance, err error) { +log.Printf("\n\n callback return services:%s \n\n", utils.ToJsonString(services)) +}, }) ``` @@ -277,24 +277,25 @@ err := namingClient.Subscribe(vo.SubscribeParam{ ```go err := namingClient.Unsubscribe(vo.SubscribeParam{ - ServiceName: "demo.go", - GroupName: "group-a", // default value is DEFAULT_GROUP - Clusters: []string{"cluster-a"}, // default value is DEFAULT - SubscribeCallback: func(services []model.Instance, err error) { - log.Printf("\n\n callback return services:%s \n\n", utils.ToJsonString(services)) - }, +ServiceName: "demo.go", +GroupName: "group-a", // default value is DEFAULT_GROUP +Clusters: []string{"cluster-a"}, // default value is DEFAULT +SubscribeCallback: func (services []model.Instance, err error) { +log.Printf("\n\n callback return services:%s \n\n", utils.ToJsonString(services)) +}, }) ``` * Get all services name:GetAllServicesInfo + ```go serviceInfos, err := namingClient.GetAllServicesInfo(vo.GetAllServiceInfoParam{ - NameSpace: "0e83cc81-9d8c-4bb8-a28a-ff703187543f", - PageNo: 1, - PageSize: 10, - }), +NameSpace: "0e83cc81-9d8c-4bb8-a28a-ff703187543f", +PageNo: 1, +PageSize: 10, +}), ``` @@ -305,9 +306,9 @@ serviceInfos, err := namingClient.GetAllServicesInfo(vo.GetAllServiceInfoParam{ ```go success, err := configClient.PublishConfig(vo.ConfigParam{ - DataId: "dataId", - Group: "group", - Content: "hello world!222222"}) +DataId: "dataId", +Group: "group", +Content: "hello world!222222"}) ``` @@ -316,8 +317,8 @@ success, err := configClient.PublishConfig(vo.ConfigParam{ ```go success, err = configClient.DeleteConfig(vo.ConfigParam{ - DataId: "dataId", - Group: "group"}) +DataId: "dataId", +Group: "group"}) ``` @@ -326,8 +327,8 @@ success, err = configClient.DeleteConfig(vo.ConfigParam{ ```go content, err := configClient.GetConfig(vo.ConfigParam{ - DataId: "dataId", - Group: "group"}) +DataId: "dataId", +Group: "group"}) ``` @@ -336,56 +337,65 @@ content, err := configClient.GetConfig(vo.ConfigParam{ ```go err := configClient.ListenConfig(vo.ConfigParam{ - DataId: "dataId", - Group: "group", - OnChange: func(namespace, group, dataId, data string) { - fmt.Println("group:" + group + ", dataId:" + dataId + ", data:" + data) - }, +DataId: "dataId", +Group: "group", +OnChange: func (namespace, group, dataId, data string) { +fmt.Println("group:" + group + ", dataId:" + dataId + ", data:" + data) +}, }) ``` + * Cancel the listening of config change event：CancelListenConfig ```go err := configClient.CancelListenConfig(vo.ConfigParam{ - DataId: "dataId", - Group: "group", +DataId: "dataId", +Group: "group", }) ``` * Search config: SearchConfig + ```go configPage, err := configClient.SearchConfig(vo.SearchConfigParam{ - Search: "blur", - DataId: "", - Group: "", - PageNo: 1, - PageSize: 10, +Search: "blur", +DataId: "", +Group: "", +PageNo: 1, +PageSize: 10, }) ``` + ## Example + We can run example to learn how to use nacos go client. + * [Config Example](./example/config) * [Naming Example](./example/service) ## Documentation + You can view the open-api documentation from the [Nacos open-api wepsite](https://nacos.io/en-us/docs/open-api.html). You can view the full documentation from the [Nacos website](https://nacos.io/en-us/docs/what-is-nacos.html). ## Contributing -Contributors are welcomed to join Nacos-sdk-go project. Please check [CONTRIBUTING.md](./CONTRIBUTING.md) about how to contribute to this project. + +Contributors are welcomed to join Nacos-sdk-go project. Please check [CONTRIBUTING.md](./CONTRIBUTING.md) about how to +contribute to this project. ## Contact + * Join us from DingDing Group(23191211). * [Gitter](https://gitter.im/alibaba/nacos): Nacos's IM tool for community messaging, collaboration and discovery. * [Twitter](https://twitter.com/nacos2): Follow along for latest nacos news on Twitter. * [Weibo](https://weibo.com/u/6574374908): Follow along for latest nacos news on Weibo (Twitter of China version). * [Nacos SegmentFault](https://segmentfault.com/t/nacos): Get the latest notice and prompt help from SegmentFault. * Email Group: - * users-nacos@googlegroups.com: Nacos usage general discussion. - * dev-nacos@googlegroups.com: Nacos developer discussion (APIs, feature design, etc). - * commits-nacos@googlegroups.com: Commits notice, very high frequency. + * users-nacos@googlegroups.com: Nacos usage general discussion. + * dev-nacos@googlegroups.com: Nacos developer discussion (APIs, feature design, etc). + * commits-nacos@googlegroups.com: Commits notice, very high frequency. diff --git a/README_CN.md b/README_CN.md index 0aed44b7..42624352 100644 --- a/README_CN.md +++ b/README_CN.md @@ -16,7 +16,7 @@ Nacos-sdk-go是Nacos的Go语言客户端，它实现了服务发现和动态配 ## 安装 使用`go get`安装SDK： ```sh -$ go get -u github.com/nacos-group/nacos-sdk-go +$ go get -u github.com/nacos-group/nacos-sdk-go/v2 ``` ## 快速使用 * ClientConfig @@ -48,10 +48,10 @@ constant.ClientConfig{ ```go constant.ServerConfig{ - ContextPath string // Nacos的ContextPath + ContextPath string // Nacos的ContextPath，默认/nacos，在2.0中不需要设置 IpAddr string // Nacos的服务地址 Port uint64 // Nacos的服务端口 - Scheme string // Nacos的服务地址前缀 + Scheme string // Nacos的服务地址前缀，默认http，在2.0中不需要设置 } ``` @@ -67,8 +67,6 @@ clientConfig := constant.ClientConfig{ NotLoadCacheAtStart: true, LogDir: "/tmp/nacos/log", CacheDir: "/tmp/nacos/cache", - RotateTime: "1h", - MaxAge: 3, LogLevel: "debug", } @@ -79,8 +77,6 @@ clientConfig := *constant.NewClientConfig( constant.WithNotLoadCacheAtStart(true), constant.WithLogDir("/tmp/nacos/log"), constant.WithCacheDir("/tmp/nacos/cache"), - constant.WithRotateTime("1h"), - constant.WithMaxAge(3), constant.WithLogLevel("debug"), ) diff --git a/common/constant/config.go b/common/constant/config.go index 8a67fe2c..f86bfc9d 100644 --- a/common/constant/config.go +++ b/common/constant/config.go @@ -19,10 +19,10 @@ package constant import "time" type ServerConfig struct { - Scheme string //the nacos server scheme - ContextPath string //the nacos server contextpath - IpAddr string //the nacos server address - Port uint64 //the nacos server port + Scheme string // the nacos server scheme,defaut=http,this is not required in 2.0 + ContextPath string // the nacos server contextpath,defaut=/nacos,this is not required in 2.0 + IpAddr string // the nacos server address + Port uint64 // nacos server port } type ClientConfig struct {