文章目录
- 一、概述
- 1、内置SDK
- 2、服务配置管理工具:ConfigService
- 3、服务注册与发现管理工具:NamingService
- 二、服务配置管理
- 1、获取配置
- (1)描述
- (2)参数
- (3)请求示例
- 2、监听配置
- (1)描述
- (2)参数
- (3)请求示例
- 3、删除监听
- (1)描述
- (2)参数
- (3)使用示例
- 4、发布配置
- (1)描述
- (2)参数
- (3)请求示例
- 5、删除配置
- (1)描述
- (2)参数
- (3)请求示例
- 三、服务发现SDK
- 1、注册实例
- (1)描述
- (2)参数
- (3)请求示例
- 2、注销实例
- (1)描述
- (2)参数
- (3)请求示例
- 3、获取全部实例
- (1)描述
- (2)参数
- (3)请求示例
- 4、获取健康或不健康实例列表
- (1)描述
- (2)参数
- (3)请求示例
- 5、获取一个健康实例
- (1)描述
- (2)参数
- (3)请求示例
- 6、监听服务
- (1)描述
- (2)参数
- (3)请求示例
- 7、取消监听服务
- (1)描述
- (2)参数
- (3)请求示例
一、概述
1、内置SDK
Nacos提供了一些客户端内置的SDK,以供我们直接对nacos中部分数据的操作。
服务配置管理包括:
- 获取配置;
- 监听配置动态变化;
- 删除监听;
- 发布配置;
- 删除配置;
服务注册与发现管理包括:
- 注册实例;
- 注销实例;
- 获取全部实例;
- 获取健康或不健康实例列表;
- 获取一个健康实例;
- 监听服务。
要想使用这些内置SDK,需要引入nacos-client包:
<dependency><groupId>com.alibaba.nacos</groupId><artifactId>nacos-client</artifactId><version>${version}</version>
</dependency>
1.X 版本最新java SDK为 1.4.4版本
2、服务配置管理工具:ConfigService
Springboot中,如果使用了nacos,会进行自动配置,并在Spring容器中注入一个NacosConfigManager(通过自动注入的方式可以注入NacosConfigManager),这个就是nacos服务配置的管理器。其中的getConfigService方法,可以获取到ConfigService,该接口就是处理服务配置的SDK。
private NacosConfigManager nacosConfigManager;
// Springboot中获取到ConfigService
ConfigService configService = nacosConfigManager.getConfigService();
而如果单纯使用JavaSDK的话,获取ConfigService 实例需要手动处理nacos的地址等信息(NacosConfigManager中也是这么做的):
// 手动获取ConfigService
String serverAddr = "{serverAddr}";
Properties properties = new Properties();
properties.put("serverAddr", serverAddr);
ConfigService configService = NacosFactory.createConfigService(properties);
ConfigService接口包含了大量的,用于处理服务配置的方法,其实现类就是NacosConfigService:
public interface ConfigService {// 获取配置String getConfig(String dataId, String group, long timeoutMs) throws NacosException;// 获取配置并注册侦听器// 如果想在程序第一次开始获取配置时自己拉取,并且注册的 Listener 用于以后的配置更新,可以保持原始代码不变,只需添加系统参数:enableRemoteSyncConfig = “true” (但有网络开销);因此,我们建议您直接使用此接口String getConfigAndSignListener(String dataId, String group, long timeoutMs, Listener listener)throws NacosException;// 在配置中添加监听器,服务器修改配置后,客户端将使用传入监听器回调。推荐异步处理,应用程序可以在 ManagerListener 中实现 getExecutor 方法,提供线程池的执行。如果提供,请使用主线程回调,可能会阻止其他配置或被其他配置阻止。void addListener(String dataId, String group, Listener listener) throws NacosException;// 发布配置boolean publishConfig(String dataId, String group, String content) throws NacosException;// 发布配置,可以选择发布的格式(properties、xml、json、text、html、yaml、unset)boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;// 删除配置boolean removeConfig(String dataId, String group) throws NacosException;// 删除监听void removeListener(String dataId, String group, Listener listener);// 获取服务状态String getServerStatus();// 关闭资源服务void shutDown() throws NacosException;
}
3、服务注册与发现管理工具:NamingService
同配置管理一样,服务注册与发现也提供了一个工具接口NamingService,在Springboot中,会自动配置一个NacosServiceManager(可以通过自动注入获取)。
NacosServiceManager中有几个用于处理服务注册与发现的方法:
getNamingService、getNamingMaintainService、isNacosDiscoveryInfoChanged、buildNamingMaintainService、buildNamingService、createNewNamingService、createNamingMaintainService、nacosServiceShutDown。
NamingService中包含了大量的方法,用于处理服务注册与发现:
public interface NamingService {// 将实例注册到服务。void registerInstance(String serviceName, String ip, int port) throws NacosException;// 将实例注册到服务void registerInstance(String serviceName, String groupName, String ip, int port) throws NacosException;// 使用指定的集群名称将实例注册到服务void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;// 使用指定的集群名称将实例注册到服务void registerInstance(String serviceName, String groupName, String ip, int port, String clusterName)throws NacosException;// 使用指定的实例属性将实例注册到服务void registerInstance(String serviceName, Instance instance) throws NacosException;// 使用指定的实例属性将实例注册到服务。void registerInstance(String serviceName, String groupName, Instance instance) throws NacosException;// 从服务中取消注册实例void deregisterInstance(String serviceName, String ip, int port) throws NacosException;// 从服务中取消注册实例void deregisterInstance(String serviceName, String groupName, String ip, int port) throws NacosException;// 从服务中取消注册具有指定集群名称的实例。void deregisterInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;// 从服务中取消注册具有指定集群名称的实例void deregisterInstance(String serviceName, String groupName, String ip, int port, String clusterName)throws NacosException;// 使用完整的实例信息和默认组名取消注册实例。void deregisterInstance(String serviceName, Instance instance) throws NacosException;// 使用完整的实例信息取消注册实例。void deregisterInstance(String serviceName, String groupName, Instance instance) throws NacosException;// 获取服务的所有实例。List<Instance> getAllInstances(String serviceName) throws NacosException;// 获取服务的所有实例。List<Instance> getAllInstances(String serviceName, String groupName) throws NacosException;// 获取服务的所有实例。List<Instance> getAllInstances(String serviceName, boolean subscribe) throws NacosException;// 获取服务的所有实例List<Instance> getAllInstances(String serviceName, String groupName, boolean subscribe) throws NacosException;// 获取服务的指定集群内的所有实例。List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;// 获取服务的指定集群内的所有实例。List<Instance> getAllInstances(String serviceName, String groupName, List<String> clusters) throws NacosException;// 获取服务的指定集群内的所有实例。List<Instance> getAllInstances(String serviceName, List<String> clusters, boolean subscribe) throws NacosException;// 获取服务的指定集群内的所有实例List<Instance> getAllInstances(String serviceName, String groupName, List<String> clusters, boolean subscribe)throws NacosException;// 获取合格的服务实例。List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;// 获取合格的服务实例。List<Instance> selectInstances(String serviceName, String groupName, boolean healthy) throws NacosException;// 获取合格的服务实例。List<Instance> selectInstances(String serviceName, boolean healthy, boolean subscribe) throws NacosException;// 获取合格的服务实例。List<Instance> selectInstances(String serviceName, String groupName, boolean healthy, boolean subscribe)throws NacosException;// 获取指定服务集群中的合格实例。List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy) throws NacosException;// 获取指定服务集群中的合格实例。List<Instance> selectInstances(String serviceName, String groupName, List<String> clusters, boolean healthy)throws NacosException;// 获取指定服务集群中的合格实例。List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy, boolean subscribe)throws NacosException;// 获取指定服务集群中的合格实例。List<Instance> selectInstances(String serviceName, String groupName, List<String> clusters, boolean healthy,boolean subscribe) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, String groupName) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, boolean subscribe) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, String groupName, boolean subscribe) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, List<String> clusters) throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, String groupName, List<String> clusters)throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, List<String> clusters, boolean subscribe)throws NacosException;// 使用预定义的负载平衡策略选择一个正常运行的服务实例。Instance selectOneHealthyInstance(String serviceName, String groupName, List<String> clusters, boolean subscribe)throws NacosException;// 订阅服务以接收实例变更事件void subscribe(String serviceName, EventListener listener) throws NacosException;// 订阅服务以接收实例变更事件void subscribe(String serviceName, String groupName, EventListener listener) throws NacosException;// 订阅服务以接收实例变更事件void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;// 订阅服务以接收实例变更事件void subscribe(String serviceName, String groupName, List<String> clusters, EventListener listener)throws NacosException;// 取消订阅服务的事件侦听器。void unsubscribe(String serviceName, EventListener listener) throws NacosException;// 取消订阅服务的事件侦听器。void unsubscribe(String serviceName, String groupName, EventListener listener) throws NacosException;// 取消订阅服务的事件侦听器。void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;// 取消订阅服务的事件侦听器。void unsubscribe(String serviceName, String groupName, List<String> clusters, EventListener listener)throws NacosException;// 从服务器获取所有服务名称ListView<String> getServicesOfServer(int pageNo, int pageSize) throws NacosException;// 从服务器获取所有服务名称ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName) throws NacosException;// 使用选择器从服务器获取所有服务名称ListView<String> getServicesOfServer(int pageNo, int pageSize, AbstractSelector selector) throws NacosException;// 使用选择器从服务器获取所有服务名称ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName, AbstractSelector selector)throws NacosException;// 获取当前客户端的所有订阅服务。List<ServiceInfo> getSubscribeServices() throws NacosException;// 获取服务器运行状况String getServerStatus();// 关闭资源服务void shutDown() throws NacosException;
}
二、服务配置管理
1、获取配置
(1)描述
用于服务启动的时候从 Nacos 获取配置。
public String getConfig(String dataId, String group, long timeoutMs) throws NacosException
(2)参数
请求:
参数名 | 参数类型 | 描述 |
---|---|---|
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 | 配置值 |
(3)请求示例
try {String serverAddr = "{serverAddr}";String dataId = "{dataId}";String group = "{group}";Properties properties = new Properties();properties.put("serverAddr", serverAddr);ConfigService configService = NacosFactory.createConfigService(properties);String content = configService.getConfig(dataId, group, 5000);System.out.println(content);
} catch (NacosException e) {// 读取配置超时或网络异常,抛出 NacosException 异常。e.printStackTrace();
}
2、监听配置
(1)描述
如果希望 Nacos 推送配置变更,可以使用 Nacos 动态监听配置接口来实现。
public void addListener(String dataId, String group, Listener listener)
(2)参数
请求参数:
参数名 | 参数类型 | 描述 |
---|---|---|
dataId | string | 配置 ID,采用类似 package.class(如com.taobao.tc.refund.log.level)的命名规则保证全局唯一性,class 部分建议是配置的业务含义。 全部字符小写。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“_”)。不超过 256 字节。 |
group | string | 配置分组,建议填写产品名:模块名(如 Nacos:Test)保证唯一性。 只允许英文字符和4种特殊字符(“.”、“:”、“-”、“_”),不超过128字节。 |
listener | Listener | 监听器,配置变更进入监听器的回调函数。 |
返回值:
参数类型 | 描述 |
---|---|
string | 配置值,初始化或者配置变更的时候通过回调函数返回该值。 |
(3)请求示例
String serverAddr = "{serverAddr}";
String dataId = "{dataId}";
String group = "{group}";
Properties properties = new Properties();
properties.put("serverAddr", serverAddr);
ConfigService configService = NacosFactory.createConfigService(properties);
String content = configService.getConfig(dataId, group, 5000);
System.out.println(content);
configService.addListener(dataId, group, new Listener() { // 添加监听@Overridepublic void receiveConfigInfo(String configInfo) {System.out.println("recieve1:" + configInfo);}@Overridepublic Executor getExecutor() {return null;}
});// 测试让主线程不退出,因为订阅配置是守护线程,主线程退出守护线程就会退出。 正式代码中无需下面代码
while (true) {try {Thread.sleep(1000);} catch (InterruptedException e) {e.printStackTrace();}
}
3、删除监听
(1)描述
取消监听配置,取消监听后配置不会再推送。
public void removeListener(String dataId, String group, Listener listener)
(2)参数
请求参数:
参数名 | 参数类型 | 描述 |
---|---|---|
dataId | string | 配置 ID,采用类似 package.class(如com.taobao.tc.refund.log.level)的命名规则保证全局唯一性,class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“_”),不超过 256 字节。 |
group | string | 配置分组 |
listener | ConfigChangeListenerAdapter | 监听器,配置变更进入监听器的回调函数。 |
(3)使用示例
String serverAddr = "{serverAddr}";
String dataId = "{dataId}";
String group = "{group}";
Properties properties = new Properties();
properties.put("serverAddr", serverAddr);
ConfigService configService = NacosFactory.createConfigService(properties);
configService.removeListener(dataId, group, yourListener);
4、发布配置
(1)描述
用于通过程序自动发布 Nacos 配置,以便通过自动化手段降低运维成本。
注意:创建和修改配置时使用的同一个发布接口,当配置不存在时会创建配置,当配置已存在时会更新配置。
public boolean publishConfig(String dataId, String group, String content) throws NacosException;@Since 1.4.1
public boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;
(2)参数
请求参数:
参数名 | 参数类型 | 描述 |
---|---|---|
dataId | string | 配置 ID,采用类似 package.class(如 com.taobao.tc.refund.log.level)的命名规则保证全局唯一性。建议根据配置的业务含义来定义 class 部分。全部字符均为小写。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“_”),不超过 256 字节。 |
group | string | 配置分组,建议填写产品名:模块名(如 Nacos:Test)来保证唯一性。只允许英文字符和 4 种特殊字符(“.”、“:”、“-”、“_”),不超过 128 字节。 |
content | string | 配置内容,不超过 100K 字节。 |
type | string | @Since 1.4.1. 配置类型,见 com.alibaba.nacos.api.config.ConfigType,默认为TEXT(properties、xml、json、text、html、yaml、unset) |
返回参数:
参数类型 | 描述 |
---|---|
boolean | 是否发布成功 |
(3)请求示例
try {// 初始化配置服务,控制台通过示例代码自动获取下面参数String serverAddr = "{serverAddr}";String dataId = "{dataId}";String group = "{group}";Properties properties = new Properties();properties.put("serverAddr", serverAddr);ConfigService configService = NacosFactory.createConfigService(properties);boolean isPublishOk = configService.publishConfig(dataId, group, "content");System.out.println(isPublishOk);
} catch (NacosException e) {// 读取配置超时或网络异常,抛出 NacosException 异常。e.printStackTrace();
}
5、删除配置
(1)描述
用于通过程序自动删除 Nacos 配置,以便通过自动化手段降低运维成本。
注意: 当配置已存在时会删除该配置,当配置不存在时会直接返回成功消息。
public boolean removeConfig(String dataId, String group) throws NacosException
(2)参数
请求参数:
参数名 | 参数类型 | 描述 |
---|---|---|
dataId | string | 配置 ID |
group | string | 配置分组 |
返回参数:
参数类型 | 描述 |
---|---|
boolean | 是否删除成功 |
(3)请求示例
try {// 初始化配置服务,控制台通过示例代码自动获取下面参数String serverAddr = "{serverAddr}";String dataId = "{dataId}";String group = "{group}";Properties properties = new Properties();properties.put("serverAddr", serverAddr);ConfigService configService = NacosFactory.createConfigService(properties);boolean isRemoveOk = configService.removeConfig(dataId, group);System.out.println(isRemoveOk);
} catch (NacosException e) {// 读取配置超时或网络异常,抛出 NacosException 异常。e.printStackTrace();
}
三、服务发现SDK
1、注册实例
(1)描述
注册一个实例到服务。
void registerInstance(String serviceName, String ip, int port) throws NacosException;void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;void registerInstance(String serviceName, Instance instance) throws NacosException;
一般情况下,服务注册通常自动注册,很少有需要我们手动去触发注册的。
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
ip | 字符串 | 服务实例IP |
port | int | 服务实例port |
clusterName | 字符串 | 集群名 |
instance | 参见代码注释 | 实例属性 |
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.registerInstance("nacos.test.3", "11.11.11.11", 8888, "TEST1");Instance instance = new Instance();
instance.setIp("55.55.55.55");
instance.setPort(9999);
instance.setHealthy(false);
instance.setWeight(2.0);
Map<String, String> instanceMeta = new HashMap<>();
instanceMeta.put("site", "et2");
instance.setMetadata(instanceMeta);Service service = new Service("nacos.test.4");
service.setApp("nacos-naming");
service.sethealthCheckMode("server");
service.setEnableHealthCheck(true);
service.setProtectThreshold(0.8F);
service.setGroup("CNCF");
Map<String, String> serviceMeta = new HashMap<>();
serviceMeta.put("symmetricCall", "true");
service.setMetadata(serviceMeta);
instance.setService(service);Cluster cluster = new Cluster();
cluster.setName("TEST5");
AbstractHealthChecker.Http healthChecker = new AbstractHealthChecker.Http();
healthChecker.setExpectedResponseCode(400);
healthChecker.setCurlHost("USer-Agent|Nacos");
healthChecker.setCurlPath("/xxx.html");
cluster.setHealthChecker(healthChecker);
Map<String, String> clusterMeta = new HashMap<>();
clusterMeta.put("xxx", "yyyy");
cluster.setMetadata(clusterMeta);instance.setCluster(cluster);naming.registerInstance("nacos.test.4", instance);
2、注销实例
(1)描述
删除服务下的一个实例。
void deregisterInstance(String serviceName, String ip, int port) throws NacosException;void deregisterInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
ip | 字符串 | 服务实例IP |
port | int | 服务实例port |
clusterName | 字符串 | 集群名 |
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.deregisterInstance("nacos.test.3", "11.11.11.11", 8888, "DEFAULT");
3、获取全部实例
(1)描述
获取服务下的所有实例。
List<Instance> getAllInstances(String serviceName) throws NacosException;List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
clusters | List | 集群列表 |
返回参数:
List 实例列表。
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
System.out.println(naming.getAllInstances("nacos.test.3"));
4、获取健康或不健康实例列表
(1)描述
根据条件获取过滤后的实例列表。
List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
clusters | List | 集群列表 |
healthy | boolean | 是否健康 |
返回参数:
List 实例列表。
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
System.out.println(naming.selectInstances("nacos.test.3", true));
5、获取一个健康实例
(1)描述
根据负载均衡算法随机获取一个健康实例。
Instance selectOneHealthyInstance(String serviceName) throws NacosException;Instance selectOneHealthyInstance(String serviceName, List<String> clusters) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
clusters | List | 集群列表 |
返回参数:
Instance 实例。
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
System.out.println(naming.selectOneHealthyInstance("nacos.test.3"));
6、监听服务
(1)描述
监听服务下的实例列表变化。
void subscribe(String serviceName, EventListener listener) throws NacosException;void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
clusters | List | 集群列表 |
listener | EventListener | 回调listener |
返回参数:
无
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.subscribe("nacos.test.3", event -> {if (event instanceof NamingEvent) {System.out.println(((NamingEvent) event).getServceName());System.out.println(((NamingEvent) event).getInstances());}
});
7、取消监听服务
(1)描述
取消监听服务下的实例列表变化。
void unsubscribe(String serviceName, EventListener listener) throws NacosException;void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
(2)参数
请求参数:
名称 | 类型 | 描述 |
---|---|---|
serviceName | 字符串 | 服务名 |
clusters | List | 集群列表 |
listener | EventListener | 回调listener |
返回参数:
无
(3)请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
naming.unsubscribe("nacos.test.3", event -> {});