概述部分

maven坐标

  1. <dependency>
  2. <groupId>com.alibaba.nacos</groupId>
  3. <artifactId>nacos-client</artifactId>
  4. <version>${version}</version>
  5. </dependency>

配置管理

获取配置

描述

用于服务启动的时候从 Nacos 获取配置。

  1. public String getConfig(String dataId, String group, long timeoutMs) throws NacosException

请求参数

参数名 参数类型 描述
dataId string 配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（"."、":"、"-"、"_"），不超过 256 字节。
group string 配置分组，建议填写产品名:模块名（Nacos:Test）保证唯一性，只允许英文字符和4种特殊字符（"."、":"、"-"、"_"），不超过128字节。
timeout long 读取配置超时时间，单位 ms，推荐值 3000。

返回值

参数类型 描述
string 配置值

请求示例

  1. try {
  2.     String serverAddr = "{serverAddr}";
  3.     String dataId = "{dataId}";
  4.     String group = "{group}";
  5.     Properties properties = new Properties();
  6.     properties.put("serverAddr", serverAddr);
  7.     ConfigService configService = NacosFactory.createConfigService(properties);
  8.     String content = configService.getConfig(dataId, group, 5000);
  9.     System.out.println(content);
  10. } catch (NacosException e) {
  11.     // TODO Auto-generated catch block
  12.     e.printStackTrace();
  13. }

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

监听配置

描述

如果希望 Nacos 推送配置变更，可以使用 Nacos 动态监听配置接口来实现。

  1. public void addListener(String dataId, String group, Listener listener)

请求参数

|
参数名
|
参数类型
|
描述

|
dataId
|
string
|
配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。 全部字符小写。只允许英文字符和 4 种特殊字符（"."、":"、"-"、"_"）。不超过 256 字节。

|
group
|
string
|
配置分组，建议填写产品名：模块名（如 Nacos:Test）保证唯一性。 只允许英文字符和4种特殊字符（"."、":"、"-"、"_"），不超过128字节。

|
listener
|
Listener
|
监听器，配置变更进入监听器的回调函数。

返回值

参数类型 描述
string 配置值，初始化或者配置变更的时候通过回调函数返回该值。

请求示例

  1. String serverAddr = "{serverAddr}";
  2. String dataId = "{dataId}";
  3. String group = "{group}";
  4. Properties properties = new Properties();
  5. properties.put("serverAddr", serverAddr);
  6. ConfigService configService = NacosFactory.createConfigService(properties);
  7. String content = configService.getConfig(dataId, group, 5000);
  8. System.out.println(content);
  9. configService.addListener(dataId, group, new Listener() {
  10.     @Override
  11.     public void receiveConfigInfo(String configInfo) {
  12.         System.out.println("recieve1:" + configInfo);
  13.     }
  14.     @Override
  15.     public Executor getExecutor() {
  16.         return null;
  17.     }
  18. });
  20. // 测试让主线程不退出，因为订阅配置是守护线程，主线程退出守护线程就会退出。 正式代码中无需下面代码
  21. while (true) {
  22.     try {
  23.         Thread.sleep(1000);
  24.     } catch (InterruptedException e) {
  25.         e.printStackTrace();
  26.     }
  27. }

删除监听

描述

取消监听配置，取消监听后配置不会再推送。

  1. public void removeListener(String dataId, String group, Listener listener)

请求参数

参数名 参数类型 描述
dataId string 配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（"."、":"、"-"、"_"），不超过 256 字节。
listener ConfigChangeListenerAdapter 监听器，配置变更进入监听器的回调函数。

使用示例

  1. String serverAddr = "{serverAddr}";
  2. String dataId = "{dataId}";
  3. String group = "{group}";
  4. Properties properties = new Properties();
  5. properties.put("serverAddr", serverAddr);
  6. ConfigService configService = NacosFactory.createConfigService(properties);
  7. configService.removeListener(dataId, group, yourListener);

发布配置

描述

用于通过程序自动发布 Nacos 配置，以便通过自动化手段降低运维成本。

注意：创建和修改配置时使用的同一个发布接口，当配置不存在时会创建配置，当配置已存在时会更新配置。

  1. public boolean publishConfig(String dataId, String group, String content) throws NacosException

请求参数

参数名 参数类型 描述
dataId string 配置 ID，采用类似 package.class（如 com.taobao.tc.refund.log.level）的命名规则保证全局唯一性。建议根据配置的业务含义来定义 class 部分。全部字符均为小写。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 256 字节。
group string 配置分组，建议填写产品名:模块名（如 Nacos:Test）来保证唯一性。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 128 字节。
content string 配置内容，不超过 100K 字节。

返回参数

参数类型 描述
boolean 是否发布成功

请求示例

  1. try {
  2.     // 初始化配置服务，控制台通过示例代码自动获取下面参数
  3.     String serverAddr = "{serverAddr}";
  4.     String dataId = "{dataId}";
  5.     String group = "{group}";
  6.     Properties properties = new Properties();
  7.     properties.put("serverAddr", serverAddr);
  8.     ConfigService configService = NacosFactory.createConfigService(properties);
  9.     boolean isPublishOk = configService.publishConfig(dataId, group, "content");
  10.     System.out.println(isPublishOk);
  11. } catch (NacosException e) {
  12.     // TODO Auto-generated catch block
  13.     e.printStackTrace();
  14. }

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

删除配置

描述

用于通过程序自动删除 Nacos 配置，以便通过自动化手段降低运维成本。

注意： 当配置已存在时会删除该配置，当配置不存在时会直接返回成功消息。

  1. public boolean removeConfig(String dataId, String group) throws NacosException

请求参数

参数名 参数类型 描述
dataId string 配置 ID
group string 配置分组

返回参数

参数类型 描述
boolean 是否删除成功

请求示例

  1. try {
  2.     // 初始化配置服务，控制台通过示例代码自动获取下面参数
  3.     String serverAddr = "{serverAddr}";
  4.     String dataId = "{dataId}";
  5.     String group = "{group}";
  6.     Properties properties = new Properties();
  7.     properties.put("serverAddr", serverAddr);
  9.     ConfigService configService = NacosFactory.createConfigService(properties);
  10.     boolean isRemoveOk = configService.removeConfig(dataId, group);
  11.     System.out.println(isRemoveOk);
  12. } catch (NacosException e) {
  13.     // TODO Auto-generated catch block
  14.     e.printStackTrace();
  15. }

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

服务发现SDK

注册实例

描述注册一个实例到服务。

  1. void registerInstance(String serviceName, String ip, int port) throws NacosException;
  3. void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;
  5. void registerInstance(String serviceName, Instance instance) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
ip 字符串 服务实例IP
port int 服务实例port
clusterName 字符串 集群名
instance 参见代码注释 实例属性

返回参数

无

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. naming.registerInstance("nacos.test.3", "11.11.11.11", 8888, "TEST1");
  4. Instance instance = new Instance();
  5. instance.setIp("55.55.55.55");
  6. instance.setPort(9999);
  7. instance.setHealthy(false);
  8. instance.setWeight(2.0);
  9. Map<String, String> instanceMeta = new HashMap<>();
  10. instanceMeta.put("site", "et2");
  11. instance.setMetadata(instanceMeta);
  13. Service service = new Service("nacos.test.4");
  14. service.setApp("nacos-naming");
  15. service.sethealthCheckMode("server");
  16. service.setEnableHealthCheck(true);
  17. service.setProtectThreshold(0.8F);
  18. service.setGroup("CNCF");
  19. Map<String, String> serviceMeta = new HashMap<>();
  20. serviceMeta.put("symmetricCall", "true");
  21. service.setMetadata(serviceMeta);
  22. instance.setService(service);
  24. Cluster cluster = new Cluster();
  25. cluster.setName("TEST5");
  26. AbstractHealthChecker.Http healthChecker = new AbstractHealthChecker.Http();
  27. healthChecker.setExpectedResponseCode(400);
  28. healthChecker.setCurlHost("USer-Agent|Nacos");
  29. healthChecker.setCurlPath("/xxx.html");
  30. cluster.setHealthChecker(healthChecker);
  31. Map<String, String> clusterMeta = new HashMap<>();
  32. clusterMeta.put("xxx", "yyyy");
  33. cluster.setMetadata(clusterMeta);
  35. instance.setCluster(cluster);
  37. naming.registerInstance("nacos.test.4", instance);

注销实例

描述

删除服务下的一个实例。

  1. void deregisterInstance(String serviceName, String ip, int port) throws NacosException;
  3. void deregisterInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
ip 字符串 服务实例IP
port int 服务实例port
clusterName 字符串 集群名

返回参数

无

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. naming.deregisterInstance("nacos.test.3", "11.11.11.11", 8888, "DEFAULT");

获取全部实例

描述

获取服务下的所有实例。

  1. List<Instance> getAllInstances(String serviceName) throws NacosException;
  3. List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
clusters List 集群列表

返回参数

List 实例列表。

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. System.out.println(naming.getAllInstances("nacos.test.3"));

获取健康或不健康实例列表

描述

根据条件获取过滤后的实例列表。

  1. List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
  3. List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
clusters List 集群列表
healthy boolean 是否健康

返回参数

List 实例列表。

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. System.out.println(naming.selectInstances("nacos.test.3", true));

获取一个健康实例

描述

根据负载均衡算法随机获取一个健康实例。

  1. Instance selectOneHealthyInstance(String serviceName) throws NacosException;
  3. Instance selectOneHealthyInstance(String serviceName, List<String> clusters) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
clusters List 集群列表

返回参数

Instance 实例。

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. System.out.println(naming.selectOneHealthyInstance("nacos.test.3"));

监听服务

描述

监听服务下的实例列表变化。

  1. void subscribe(String serviceName, EventListener listener) throws NacosException;
  3. void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
clusters List 集群列表
listener EventListener 回调listener

返回参数

无

请求示例

  1. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  2. naming.subscribe("nacos.test.3", event -> {
  3.     if (event instanceof NamingEvent) {
  4.         System.out.println(((NamingEvent) event).getServceName());
  5.         System.out.println(((NamingEvent) event).getInstances());
  6.     }
  7. });

取消监听服务

描述

取消监听服务下的实例列表变化。

  1. void unsubscribe(String serviceName, EventListener listener) throws NacosException;
  3. void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

请求参数

名称 类型 描述
serviceName 字符串 服务名
clusters List 集群列表
listener EventListener 回调listener

返回参数

无

请求示例

  2. NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
  3. naming.unsubscribe("nacos.test.3", event -> {});

原文: https://nacos.io/zh-cn/docs/sdk.html