Java SDK

概述部分

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

请求参数

参数名参数类型描述
dataIdstring配置 ID,采用类似 package.class(如com.taobao.tc.refund.log.level)的命名规则保证全局唯一性,class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符(”.”、”:”、”-“、”“),不超过 256 字节。
groupstring配置分组,建议填写产品名:模块名(Nacos:Test)保证唯一性,只允许英文字符和4种特殊字符(”.”、”:”、”-“、”“),不超过128字节。
timeoutlong读取配置超时时间,单位 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. });
  19. // 测试让主线程不退出,因为订阅配置是守护线程,主线程退出守护线程就会退出。 正式代码中无需下面代码
  20. while (true) {
  21. try {
  22. Thread.sleep(1000);
  23. } catch (InterruptedException e) {
  24. e.printStackTrace();
  25. }
  26. }

删除监听

描述

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

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

请求参数

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

使用示例

  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;
  2. @Since 1.4.1
  3. public boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID,采用类似 package.class(如 com.taobao.tc.refund.log.level)的命名规则保证全局唯一性。建议根据配置的业务含义来定义 class 部分。全部字符均为小写。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“”),不超过 256 字节。
groupstring配置分组,建议填写产品名:模块名(如 Nacos:Test)来保证唯一性。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“”),不超过 128 字节。
contentstring配置内容,不超过 100K 字节。
typestring@Since 1.4.1. 配置类型,见 com.alibaba.nacos.api.config.ConfigType,默认为TEXT

返回参数

参数类型描述
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

请求参数

参数名参数类型描述
dataIdstring配置 ID
groupstring配置分组

返回参数

参数类型描述
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 isRemoveOk = configService.removeConfig(dataId, group);
  10. System.out.println(isRemoveOk);
  11. } catch (NacosException e) {
  12. // TODO Auto-generated catch block
  13. e.printStackTrace();
  14. }

异常说明

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

服务发现SDK

注册实例

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

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

请求参数

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

返回参数

请求示例

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

注销实例

描述

删除服务下的一个实例。

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

请求参数

名称类型描述
serviceName字符串服务名
ip字符串服务实例IP
portint服务实例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;
  2. List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;

请求参数

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

返回参数

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;
  2. List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy) throws NacosException;

请求参数

名称类型描述
serviceName字符串服务名
clustersList集群列表
healthyboolean是否健康

返回参数

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;
  2. Instance selectOneHealthyInstance(String serviceName, List<String> clusters) throws NacosException;

请求参数

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

返回参数

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;
  2. void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

请求参数

名称类型描述
serviceName字符串服务名
clustersList集群列表
listenerEventListener回调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;
  2. void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

请求参数

名称类型描述
serviceName字符串服务名
clustersList集群列表
listenerEventListener回调listener

返回参数

请求示例

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