Nacos Java SDK 使用手册

最新推荐文章于 2025-02-14 11:07:25 发布
原创 最新推荐文章于 2025-02-14 11:07:25 发布 · 1.2k 阅读 · 25 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#nacos #java #微服务

1. 引用概述

Maven 坐标

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>${version}</version>
</dependency>

注意：由于Nacos Java SDK在2.0版本后引入了gRPC，为了避免用户业务引入的gRPC版本不同导致冲突，使用了shaded技术将部分依赖直接封装进nacos-client中，导致nacos-client较大。 如果用户未自行引入gRPC或确认版本无冲突，希望使用纯净版的nacos-client以减小依赖，可以使用classifier来指定使用纯净版。

    <properties>
        <!-- 2.1.2版本以上支持纯净版客户端 -->
        <nacos.version>2.4.2</nacos.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.alibaba.nacos</groupId>
            <artifactId>nacos-client</artifactId>
            <version>${nacos.version}</version>
            <!-- 指定纯净版SDK -->
            <classifier>pure</classifier>
        </dependency>
        <!-- 使用纯净版时必须要引入同版本nacos-api和nacos-common，否则可能出现运行时找不到类的问题 -->
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>nacos-common</artifactId>
            <version>${nacos.version}</version>
        </dependency>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>nacos-api</artifactId>
            <version>${nacos.version}</version>
        </dependency>
    </dependencies>

2. 初始化SDK

Nacos 初始化SDK仅需要使用 NacosFactory 类进行不同模块的创建即可：

String serverAddr = "localhost:8848";

# 初始化配置中心的Nacos Java SDK
ConfigService configService = NacosFactory.createConfigService(serverAddr);

# 初始化配置中心的Nacos Java SDK
NamingService namingService = NacosFactory.createNamingService(serverAddr);

如果初始化SDK时，还需要配置一些参数，可以使用 Properties 类进行配置：

Properties properties = new Properties();
# 指定Nacos-Server的地址
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
# 指定Nacos-SDK的命名空间
properties.setProperty(PropertyKeyConst.NAMESPACE, "${namespaceId}");

# 初始化配置中心的Nacos Java SDK
ConfigService configService = NacosFactory.createConfigService(properties);

# 初始化配置中心的Nacos Java SDK
NamingService namingService = NacosFactory.createNamingService(properties);

更多初始化时所涉及的参数配置，请参考Java SDK 配置参数。

注意：一个Nacos Java SDK实例只能用于获取同一个命名空间下的配置和服务，如果要获取不同的命名空间下的配置或服务，需要创建不同的Nacos Java SDK实例。

3. 配置管理 API

3.1. 获取配置

描述

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

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）保证唯一性，只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
timeoutlong读取配置超时时间，单位 ms，推荐值 3000。
返回值
参数类型描述
string配置值
请求示例
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) {
    e.printStackTrace();
}
异常说明

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

3.2. 监听配置

描述

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

public void addListener(String dataId, String group, Listener listener)
请求参数
参数名参数类型描述
dataIdstring配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupstring配置分组，建议填写产品名:模块名（Nacos）保证唯一性，只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
listenerListener监听器，配置变更进入监听器的回调函数。
返回值
参数类型描述
string配置值，初始化或者配置变更的时候通过回调函数返回该值。
请求示例
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() {
    @Override
    public void receiveConfigInfo(String configInfo) {
        System.out.println("recieve1:" + configInfo);
    }
    @Override
    public Executor getExecutor() {
        return null;
    }
});

// 测试让主线程不退出，因为订阅配置是守护线程，主线程退出守护线程就会退出。 正式代码中无需下面代码
while (true) {
    try {
        Thread.sleep(1000);
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
}

3.3. 删除监听

描述

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

public void removeListener(String dataId, String group, Listener listener)
请求参数
参数名参数类型描述
dataIdstring配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupstring配置分组
listenerConfigChangeListenerAdapter监听器，配置变更进入监听器的回调函数。
使用示例
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);

3.4. 发布配置

描述

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

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

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

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是否发布成功
请求示例
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) {
    e.printStackTrace();
}
异常说明

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

3.5. 删除配置

描述

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

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

public boolean removeConfig(String dataId, String group) throws NacosException
请求参数
参数名参数类型描述
dataIdstring配置 ID
groupstring配置分组
返回参数
参数类型描述
boolean是否删除成功
请求示例
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) {
    e.printStackTrace();
}
异常说明

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

3.6. 带监听器的获取配置

描述

如果希望在程序首次启动获取配置时自行注册的Listener用于以后配置更新，建议您直接使用该接口。

该接口等价于先使用getConfig之后再使用addListener。

String getConfigAndSignListener(String dataId, String group, long timeoutMs, Listener listener) throws NacosException;
请求参数
参数名参数类型描述
dataIdstring配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupstring配置分组，建议填写产品名:模块名（Nacos）保证唯一性，只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
timeoutlong读取配置超时时间，单位 ms，推荐值 3000。
listenerListener监听器，配置变更进入监听器的回调函数。
返回值
参数类型描述
string配置值
请求示例
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.getConfigAndSignListener(dataId, group, 5000, new Listener() {
        @Override
        public void receiveConfigInfo(String configInfo) {
            System.out.println("recieve1:" + configInfo);
        }
        @Override
        public Executor getExecutor() {
            return null;
        }
    });
    System.out.println(content);
} catch (NacosException e) {
    e.printStackTrace();
}
异常说明

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

3.7. 带Compare-And-Swap（CAS）的发布配置

描述

直接使用publishConfig进行配置发布时，可能存在不同进程间并发的配置覆盖问题，此时可以使用带Compare-And-Swap（CAS）的发布配置API，来保证不会此类情形。

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

boolean publishConfigCas(String dataId, String group, String content, String casMd5) throws NacosException;

boolean publishConfigCas(String dataId, String group, String content, String casMd5, String type) throws NacosException;
请求参数
参数名参数类型描述
dataIdstring配置 ID，采用类似 package.class（如 com.taobao.tc.refund.log.level）的命名规则保证全局唯一性。建议根据配置的业务含义来定义 class 部分。全部字符均为小写。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 256 字节。
groupstring配置分组，建议填写产品名:模块名（如 Nacos:Test）来保证唯一性。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 128 字节。
contentstring配置内容，不超过 100K 字节。
casMd5string前配置内容的md5
typestring配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为TEXT
返回参数
参数类型描述
boolean是否发布成功
请求示例
try {
    // 初始化配置服务，控制台通过示例代码自动获取下面参数
    String serverAddr = "{serverAddr}";
    String dataId = "{dataId}";
    String group = "{group}";
    String oldContent = "oldContent";
    String oldContentMd5 = "63fb636909f1ebad67110e49117e6de4";
    Properties properties = new Properties();
    properties.put("serverAddr", serverAddr);
    ConfigService configService = NacosFactory.createConfigService(properties);
    # 首次发布，casMd5传入null。
    boolean isPublishOk = configService.publishConfigCas(dataId, group, oldContent, null);
    System.out.println(isPublishOk);
    # old Md5 正确，变成成功
    isPublishOk = configService.publishConfigCas(dataId, group, "newContent", oldContentMd5);
    System.out.println(isPublishOk);
    # old Md5 错误，变成失败
    isPublishOk = configService.publishConfigCas(dataId, group, "newContent2", oldContentMd5);
    System.out.println(isPublishOk);
} catch (NacosException e) {
    e.printStackTrace();
}
异常说明

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

4. 服务发现API

4.1. 注册实例

描述

注册一个实例到服务。

由于同一个Nacos Client实例，仅能向一个服务注册一个实例；若同一个Nacos Client实例多次向同一个服务注册实例，后注册的实例将会覆盖先注册的实例。 若有存在代理注册的场景，请使用批量注册服务实例

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
ip字符串服务实例IP无，必填
portint服务实例port无，必填
clusterName字符串集群名DEFAULT
instance参见代码注释实例属性无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

# 以下注册请求所造成的结果均一致, 注册分组名为`DEFAULT_GROUP`, 服务名为`nacos.test.service`的实例，实例的ip为`127.0.0.1`, port为`8848`, clusterName为`DEFAULT`.
naming.registerInstance("nacos.test.service", "127.0.0.1", 8848);
naming.registerInstance("nacos.test.service", "DEFAULT_GROUP", "127.0.0.1", 8848);
naming.registerInstance("nacos.test.service", "127.0.0.1", 8848, "DEFAULT");
naming.registerInstance("nacos.test.service", "DEFAULT_GROUP", "127.0.0.1", 8848, "DEFAULT");
Instance instance = new Instance();
instance.setIp("127.0.0.1");
instance.setPort(8848);
instance.setClusterName("DEFAULT");
naming.registerInstance("nacos.test.service", instance);
naming.registerInstance("nacos.test.service", "DEFAULT_GROUP", instance);

4.2. 注销实例

描述

删除服务下的一个实例。

若该服务是通过批量注册服务实例进行注册，使用注销实例进行注销时，将注销所有批量注册的实例。 若仅希望注销部分批量注册的实例，请使用批量注销服务实例

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);
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
ip字符串服务实例IP无，必填
portint服务实例port无，必填
clusterName字符串集群名DEFAULT
instance参见代码注释实例属性无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
# 以下注销请求所造成的结果均一致, 注销分组名为`DEFAULT_GROUP`, 服务名为`nacos.test.service`的实例，实例的ip为`127.0.0.1`, port为`8848`, clusterName为`DEFAULT`.
naming.deregisterInstance("nacos.test.service", "127.0.0.1", 8848);
naming.deregisterInstance("nacos.test.service", "DEFAULT_GROUP", "127.0.0.1", 8848);
naming.deregisterInstance("nacos.test.service", "127.0.0.1", 8848, "DEFAULT");
naming.deregisterInstance("nacos.test.service", "DEFAULT_GROUP", "127.0.0.1", 8848, "DEFAULT");
Instance instance = new Instance();
instance.setIp("127.0.0.1");
instance.setPort(8848);
instance.setClusterName("DEFAULT");
naming.deregisterInstance("nacos.test.service", instance);
naming.deregisterInstance("nacos.test.service", "DEFAULT_GROUP", instance);

4.3. 获取全部实例

描述

获取服务下的所有实例。

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
subscribeBoolean是否订阅服务，为true时将会订阅该服务，同时查询优先通过内存缓存；为false时将直接查询Nacos Servertrue
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
返回参数

List<Instance> 实例列表。

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
# 以下查询请求所造成的结果均一致.
System.out.println(naming.getAllInstances("nacos.test.service"));
System.out.println(naming.getAllInstances("nacos.test.service", "DEFAULT_GROUP"));
System.out.println(naming.getAllInstances("nacos.test.service", true));
System.out.println(naming.getAllInstances("nacos.test.service", "DEFAULT_GROUP", true));
System.out.println(naming.getAllInstances("nacos.test.service", new ArrayList<>()));
System.out.println(naming.getAllInstances("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>()));
System.out.println(naming.getAllInstances("nacos.test.service", new ArrayList<>(), true));
System.out.println(naming.getAllInstances("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), true));

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

描述

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

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
subscribeBoolean是否订阅服务，为true时将会订阅该服务，同时查询优先通过内存缓存；为false时将直接查询Nacos Servertrue
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
healthyboolean是否健康，为true时仅会返回健康的实例列表，反之则返回不健康的实例列表。true
返回参数

List<Instance> 实例列表。

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
# 以下查询请求所造成的结果均一致.
System.out.println(naming.selectInstances("nacos.test.service", true));
System.out.println(naming.selectInstances("nacos.test.service", "DEFAULT_GROUP", true));
System.out.println(naming.selectInstances("nacos.test.service", true, true));
System.out.println(naming.selectInstances("nacos.test.service", "DEFAULT_GROUP", true, true));
System.out.println(naming.selectInstances("nacos.test.service", new ArrayList<>(), true));
System.out.println(naming.selectInstances("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), true));
System.out.println(naming.selectInstances("nacos.test.service", new ArrayList<>(), true, true));
System.out.println(naming.selectInstances("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), true, true));

4.5. 获取一个健康实例

描述

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

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
subscribeBoolean是否订阅服务，为true时将会订阅该服务，同时查询优先通过内存缓存；为false时将直接查询Nacos Servertrue
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
返回参数

Instance 实例。

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
# 以下查询请求所造成的结果均一致.
System.out.println(naming.selectOneHealthyInstance("nacos.test.service"));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", "DEFAULT_GROUP"));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", true));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", "DEFAULT_GROUP", true));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", new ArrayList<>()));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>()));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", new ArrayList<>(), true));
System.out.println(naming.selectOneHealthyInstance("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), true));

4.6. 监听服务

描述

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

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
listenerEventListener回调listener无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
EventListener serviceListener = event -> {
    if (event instanceof NamingEvent) {
        System.out.println(((NamingEvent) event).getServiceName());
        System.out.println(((NamingEvent) event).getInstances());
    }
};
naming.subscribe("nacos.test.service", serviceListener);
naming.subscribe("nacos.test.service", "DEFAULT_GROUP", serviceListener);
naming.subscribe("nacos.test.service", new ArrayList<>(), serviceListener);
naming.subscribe("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), serviceListener);
使用自定义线程池进行异步监听

Nacos 支持使用自定义线程池进行异步监听回调，只需要将EventListener更换为AbstractEventListener，并实现Executor getExecutor()方法来返回自定义的线程池，Nacos Client将在服务发生变更时使用该线程池进行异步回调。

NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
ExecutorService executorService = Executors.newFixedThreadPool(1);
EventListener serviceListener = new AbstractEventListener() {
    @Override
    public void onEvent(Event event) {
        if (event instanceof NamingEvent) {
            System.out.println(((NamingEvent) event).getServiceName());
            System.out.println(((NamingEvent) event).getInstances());
        }
    }

    @Override
    public Executor getExecutor() {
        return executorService;
    }
};
naming.subscribe("nacos.test.service", serviceListener);
监听服务变化的差值

Nacos 从2.4.0版本你开始，支持监听服务变化的差值，即和之前相比，有哪些实例被新增，移除和修改，只需要将EventListener更换为AbstractNamingChangeListener，实现onChange方法即可。onChange中会传入NamingChangeEvent,其中InstancesDiff记录了此次通知和之前相比的实例变化。

同时为了防止差值的错误和异常，NamingChangeEvent仍然可以通过getInstances方法获取最终的服务实例列表。

NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
ExecutorService executorService = Executors.newFixedThreadPool(1);
EventListener serviceListener = new AbstractNamingChangeListener() {
    @Override
    public void onChange(NamingChangeEvent event) {
        if (event.isAdded()) {
            System.out.println(event.getAddedInstances());
        }
        if (event.isRemoved()) {
            System.out.println(event.getRemovedInstances());
        }
        if (event.isModified()) {
            System.out.println(event.getModifiedInstances());
        }
    }

    @Override
    public Executor getExecutor() {
        return executorService;
    }
};
naming.subscribe("nacos.test.service", serviceListener);

4.7. 取消监听服务

描述

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

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;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
listenerEventListener回调listener无，必填

注意：取消监听服务时，需要使用进行订阅时的listener进行取消监听，否则可能造成取消监听失败。

返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
EventListener serviceListener = event -> {};
naming.subscribe("nacos.test.service", serviceListener);
naming.unsubscribe("nacos.test.service", serviceListener);
naming.unsubscribe("nacos.test.service", "DEFAULT_GROUP", serviceListener);
naming.unsubscribe("nacos.test.service", new ArrayList<>(), serviceListener);
naming.unsubscribe("nacos.test.service", "DEFAULT_GROUP", new ArrayList<>(), serviceListener);

4.8. 批量注册服务实例

描述

注册一系列实例到指定服务。

由于同一个Nacos Client实例，仅能向一个服务注册一个实例；若同一个Nacos Client实例多次向同一个服务注册实例，后注册的实例将会覆盖先注册的实例。 考虑到社区存在代理注册的场景：如Nacos-Sync， Proxy-Registry等，需要在一个客户端中注册同一个服务的不同实例，社区新增了批量注册服务实例的功能。

void batchRegisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
instancesInstance的List服务实例列表无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

Instance instance1 = new Instance();

instance1.setIp("127.0.0.1");

instance1.setPort(8848);

instance1.setClusterName("DEFAULT");

Instance instance2 = new Instance();

instance2.setIp("127.0.0.1");

instance2.setPort(9848);

instance2.setClusterName("DEFAULT");

List<Instance> instances = new ArrayList<>(2);

instances.add(instance1);

instances.add(instance2);

naming.batchRegisterInstance("nacos.test.service", "DEFAULT_GROUP", instances);

4.9. 批量注销服务实例

描述

从指定服务中注销一系列实例。

针对使用了批量注册服务实例的用户设计，允许用户选择一部分或全部批量注册的实例进行注销。

void batchDeregisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
instancesInstance的List服务实例列表无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

Instance instance1 = new Instance();

instance1.setIp("127.0.0.1");

instance1.setPort(8848);

instance1.setClusterName("DEFAULT");

Instance instance2 = new Instance();

instance2.setIp("127.0.0.1");

instance2.setPort(9848);

instance2.setClusterName("DEFAULT");

List<Instance> instances = new ArrayList<>(2);

instances.add(instance1);

instances.add(instance2);

naming.batchRegisterInstance("nacos.test.service", "DEFAULT_GROUP", instances);

naming.batchDeregisterInstance("nacos.test.service", "DEFAULT_GROUP", instances);

4.10. 带选择器的监听服务

描述

使用自定义逻辑的选择器，监听服务下的实例列表变化，当服务列表发生变化时，会使用自定义的选择器进行过滤，当过滤后的数据仍然有变化时，才会进行回调通知。

void subscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;

void subscribe(String serviceName, String groupName, NamingSelector selector, EventListener listener) throws NacosException;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
selectorNamingSelector自定义的数据选择器无，必填
listenerEventListener回调listener无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

EventListener serviceListener = event -> {

if (event instanceof NamingEvent) {

System.out.println(((NamingEvent) event).getServiceName());

System.out.println(((NamingEvent) event).getInstances());

}

};

# 只会选择订阅ip为`127.0`开头的实例。

NamingSelector selector = NamingSelectorFactory.newIpSelector("127.0.*");

naming.subscribe("nacos.test.service", "DEFAULT_GROUP", selector, serviceListener);
预设提供的数据选择器

Nacos Client 提供了预设的多种数据选择器以供默认场景下使用：

  1. Cluster选择器，NamingSelectorFactory.newClusterSelector(Collection<String> clusters), 当订阅服务时传入了clusters参数，Nacos Client将自动使用该数据选择器。
  2. Ip选择器，NamingSelectorFactory.newClusterSelector(String ipRegex)，当实例的ip满足传入的ipRegex时，才会被通知回调。
  3. 元数据选择器，NamingSelectorFactory.newMetadataSelector(Map<String, String> metadata)，当实例的元数据包含所有传入选择器的metadata时，才会被通知回调。
  4. 任意元数据选择器，NamingSelectorFactory.newMetadataSelector(Map<String, String> metadata, false),当实例的元数据包含任意一对传入选择器的metadata时，才会被通知回调。
开发自定义数据选择器

多数情况下， 开发自定义数据选择器只需要创建DefaultNamingSelector即可，在构建时传入一个Predicate<Instance> filter作为单个实例是否满足您过滤条件的结果，类似Java中stream的filter方法，如此您仅需要考虑单个实例的过滤条件即可。

若是DefaultNamingSelector无法满足需求，您需要实现NamingSelector接口，根据传入的NamingContext进行复杂的逻辑校验，最后输出NamingResult给Nacos Client。

4.11. 取消带选择器的监听服务

描述

使用自定义逻辑的选择器进行监听服务下的实例列表变化，那么在取消监听时需要使用取消带选择器的监听服务的API才能正确取消监听。

注意：取消监听时需要传入监听时使用的selector和listener，否则可能导致取消监听失败。

void unsubscribe(String serviceName, NamingSelector selector, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, String groupName, NamingSelector selector, EventListener listener) throws NacosException;
请求参数
名称类型描述默认值
serviceName字符串服务名无，必填
groupName字符串分组名DEFAULT_GROUP
clusters字符串列表实例的clusterName，空列表时将查询所有实例。空列表
selectorNamingSelector自定义的数据选择器无，必填
listenerEventListener回调listener无，必填
返回参数

无

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

EventListener serviceListener = event -> {

if (event instanceof NamingEvent) {

System.out.println(((NamingEvent) event).getServiceName());

System.out.println(((NamingEvent) event).getInstances());

}

};

# 只会选择订阅ip为`127.0`开头的实例。

NamingSelector selector = NamingSelectorFactory.newIpSelector("127.0.*");

naming.subscribe("nacos.test.service", "DEFAULT_GROUP", selector, serviceListener);

naming.unsubscribe("nacos.test.service", "DEFAULT_GROUP", selector, serviceListener);

4.12. 分页获取服务列表

描述

通过分页的方式获取当前客户端所在命名空间的服务列表

ListView<String> getServicesOfServer(int pageNo, int pageSize) throws NacosException;

ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName) throws NacosException;

注意，使用AbstractSelector的getServicesOfServer方法已废弃，请勿继续使用。

请求参数
名称类型描述默认值
pageNoint分页序号无，必填
pageSizeint分页中每页的服务个数无，必填
groupName字符串分组名DEFAULT_GROUP
返回参数

服务名列表: ListView

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

# 等价于`naming.getServicesOfServer(1, 10, "DEFAULT_GROUP");`

ListView<String> result = naming.getServicesOfServer(1, 10);

System.out.println(result.getCount());

System.out.println(result.getData());

4.13. 获取当前客户端所监听的服务列表

描述

获取当前客户端所的所有服务列表

List<ServiceInfo> getSubscribeServices() throws NacosException;
请求参数

无

返回参数

服务列表: List

请求示例
NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));

System.out.println(naming.getSubscribeServices());

5. Java SDK的生命周期

Nacos的Java SDK 生命周期从创建时开始，到调用shutdown()方法时结束，期间对应创建的线程池、连接等均会始终保留，及时连接断开，也会不断重试重新建立连接。

因此在使用时需要注意应用中创建的Nacos Java SDK的实例个数，避免造成线程池和连接的泄漏，在更换Nacos Java SDK实例时，切记调用shutdown()方法，同时在应用中应尽量复用同一个Nacos Java SDK实例，避免频繁的初始化实例。

向阳1218
关注
python-74-Nacos技术之单机模式安装Nacos并使用Python操作Nacos
qq_20466211的博客
05-12 307
在windows中单机模式安装Nacos，并使用Python应用注册中心和配置中心功能。
Nacos故障排查与性能优化详解
最新发布
weixin_42593797的博客
06-10 1659
本文深入分析了Nacos在微服务架构中的常见故障及优化策略。主要内容包括：1) 服务注册失败排查，涉及网络连通性、客户端配置检查；2) 配置刷新失效问题，强调监听器注册和日志分析；3) 服务发现异常处理方法。性能优化方面，从服务端JVM调优、数据库配置到客户端心跳频率调整、缓存优化进行全面指导，并提供了集群部署的最佳实践。文章通过具体代码示例和配置说明，为开发者提供了实用的Nacos运维手册。
nacos java sdk 使用demo
chudaxiakkk的专栏
03-28 1114
上一篇，介绍了nacos服务端，客户端和springCloud的版本选择。 我研究nacos，计划是先把客户端琢磨透，再去看服务端源码。 目录 1.看官网说明 2.跟随官网写demo 配置管理demo 服务发现demo 我的源码下载 1.看官网说明 java sdk 我选择的版本是最新的稳定版本1.4.1 <!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client --> ...
Nacos的SDK使用
whatzhang007的博客
07-05 2189
需求说明： 使用nacos的sdk对config配置进行代码级别的管理，对服务和订阅者进行维护 接口和SDK SDK文档：https://nacos.io/zh-cn/docs/sdk.html 接口文档：https://nacos.io/zh-cn/docs/open-api.html 两者本质是一样的 示例（获取配置） 代码示例（quarkus框架） import com.alibaba.nacos.api.NacosFactory; import com.alibaba.nacos.api.Pro
使用 Nacos SDK 向 Nacos 注册服务 使用 Nacos SDK 获取某个服务的所有实例
flamesfather的博客
02-14 349
【代码】使用 Nacos SDK 向 Nacos 注册服务 使用 Nacos SDK 获取某个服务的所有实例。
Nacos的Java SDK
这个需求，做不了
12-21 1898
Nacos的java sdk的简单使用
Nacos系列——Java SDK（2.x版本）2-1
qq_51553982的博客
12-19 899
本工程是Nacos的Java SDK 2.x版本的实现，并非官方文档而是本人经过学习后自己构建的工程，官方文档目前还未更新，仅供学习交流，请勿进行任何商业用途。
Rust 从入门到放弃，再入门到贡献 nacos-sdk-rust
蔡梦缘的博客
12-18 1808
Rust 上手难度大？我想是的。从文章标题便可知一二，小编水平有限经历了多次入门，得来的经验之谈。本文不涉及详细的技术剖析，仅表达入门的心路历程，供客官参考。
nacos编译后的安装包
02-21
3. **文档**：详细的用户手册、API 文档和示例代码，帮助开发者理解和使用 Nacos。 4. **脚本**：启动、停止、升级等操作的脚本，方便运维人员管理 Nacos 服务。 总的来说，Nacos 是一款强大的工具，尤其在微服务...
注册中心Nacos
liushangzaibeijing的博客
01-28 1975
本篇文章是springCloud alibaba专栏的第一篇博文，注册中心nacos学习，文章分为3部分注册中心的作用、nacos与springBoot整合、nacos的相关原理。其中nacos相关原理针对服务注册、服务发现、服务变更通知以及心跳检测等注册中心核心功能进行了源码分析，希望能对读者对与nacos的学习有所帮助。
Nacos系列：Nacos的Java SDK使用
weixin_33895516的博客
02-24 484
Maven依赖 Nacos提供完整的Java SDK，便于配置管理和服务发现及管理，以 Nacos-0.8.0 版本为例 添加Maven依赖： <dependency> <groupId>com.alibaba.nacos</groupId> <artifactId>nacos-client</artifactId> ...
Nacos使用JavaSDK，Nacos 动态监听配置，Nacos动态发布配置，Nacos动态获取实例
秃了也弱了
09-13 1439
Nacos提供了一些客户端内置的SDK，以供我们直接对nacos中部分数据的操作。获取配置；监听配置动态变化；删除监听；发布配置；删除配置；注册实例；注销实例；获取全部实例；获取健康或不健康实例列表；获取一个健康实例；监听服务。要想使用这些内置SDK，需要引入nacos-client包：
Nacos Java SDK
深圳市多克创新科技有限公司
09-05 416
Nacos Java SDK
Nacos简介
相逢一笑
03-18 8138
Nacos 第一次映入眼帘时，是在18年dubbo的一次线下沙龙中，那时还是v0.1.0版本；而如今，nacos已经经历过了可生产环境使用的 v0.8.0 Pre-GA版，到了v0.9.0版本。下面，就一起来简单了解一下nacos。 nacos是什么？ Nacos 是一个集服务动态发现、服务配置、服务元数据及流量管理于一体的管理中心，能帮助我们更好的发现、配置和管理微服务。 Nacos 支持几乎...
nacos采用java sdk方式获取配置及监听配置
liaomingwu的专栏
01-02 2114
对于某些简单的场景，直接使用nacos java sdk方式访问nacos配置会更加简洁和方便。
【2.2】Java微服务：nacos的使用
Meteors.的博客
08-06 3992
本文主要介绍Nacos的安装部署以及简单的入门（单机服务注册、负载均衡、存储模型等）
Nacos（十二）之Java SDK
茅坤宝骏氹的博客
02-01 899
转载自Java SDK 概述部分 Maven 坐标 <dependency> <groupId>com.alibaba.nacos</groupId> <artifactId>nacos-client</artifactId> <version>${version}</version> </dependency> 配置管理 获取配置 描述 用于服务启动的时候从 Nacos 获取配置。 p..
Java 系列 Nacos
cheers_bin的博客
04-12 4007
Nacos（Naming Configuration Service） 是一个易于使用的动态服务发现、配置和服务管理平台，用于构建云原生应用程序服务发现是微服务架构中的关键组件之一。Nacos 致力于帮助您发现、配置和管理微服务。Nacos 提供了一组简单易用的特性集，帮助您快速实现动态服务发现、服务配置、服务元数据及流量管理。Nacos 帮助您更敏捷和容易地构建、交付和管理微服务平台。
bscp-java-sdk：蓝鲸BSCP项目的Java配置访问工具
该文件极有可能包含了 SDK 的核心 JAR 包、依赖说明文档（如 pom.xml 或 build.gradle）、使用示例代码、配置模板以及 API 使用手册等内容。开发者在解压后可通过导入项目结构至 IDE（如 IntelliJ IDEA 或 Eclipse）...
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值