注册发现

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

服务注册

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.DiscoveryAPIFactory, 使用 DiscoveryAPIFactory 中的方法进行构造一个 ProviderAPI SDK 实例

import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
    ProviderAPI providerAPI = DiscoveryAPIFactory.createProviderAPI();
}

注册请求体

InstanceRegisterRequest request = new InstanceRegisterRequest();
// 设置实例所属服务信息
request.setService(service);
// 设置实例所属服务的命名空间信息
request.setNamespace(namespace);
// 设置实例的 host 信息
request.setHost(host);
// 设置实例的端口信息
request.setPort(port);
// 可选，资源访问Token，即用户/用户组访问凭据，仅当服务端开启客户端鉴权时才需配置
request.setToken(token);
// 设置实例版本
request.setVersion(version);
// 设置实例的协议
request.setProtocol(protocol);
// 设置实例权重
request.setWeight(weight);
// 设置实例的标签
request.setMetadata(metadata);
// 设置实例地理位置 zone 信息
request.setZone(zone);
// 设置实例地理位置 region 信息
request.setRegion(region);
// 设置实例地理位置 campus 信息
request.setCampus(campus);
// 设置心跳健康检查ttl，单位为s，不填默认为5s，TTL的取值范围为 (0s, 60s]
// 开启了心跳健康检查，客户端必须以TTL间隔上报心跳
// 健康检查服务器3个TTL未受到心跳则将实例置为不健康
request.setTtl(ttl);

说明： 鉴权文档可参考权限控制。

发起注册请求

你在初始化完 InstanceRegisterRequest 结构体后，只需要调用 ProviderAPI.RegisterInstance 方法即可完成实例注册，并且 RegisterInstance 方法内部会自动维护实例的心跳上报。

InstanceRegisterResponse registerResp = providerAPI.registerInstance(registerRequest)

服务发现

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.DiscoveryAPIFactory, 使用 DiscoveryAPIFactory 中的方法进行构造一个 ConsumerAPI SDK 实例

import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
    ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
}

发现服务实例

GetAllInstances

直接返回目标服务下的所有实例，包括不健康、隔离、权重为0、被熔断的实例，也会在返回的实例列表中。

GetAllInstancesRequest request = new GetAllInstancesRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);
// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getAllInstance(request);

GetHealthyInstances

每次获取一批可用服务提供者实例。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

GetInstancesRequest request = new GetInstancesRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);

// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getInstances(request);

GetOneInstances

每次仅获取一个可用服务提供者实例，该方法会依次执行路由、负载均衡流程。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

说明：

执行路由流程的条件

配置了 GetOneInstanceRequest.ServiceInfo.Metadata 属性，会触发自定义路由流程
设置了 GetOneInstanceRequest.Metadata 属性，会触发元数据路由流程

public class Criteria {
    /**
     * 指定负载均衡策略
     */
    private String lbPolicy;
    /**
     * 一致性hash的key
     */
    private String hashKey;
}

GetOneInstanceRequest request = new GetOneInstanceRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);
// 可选，元数据信息，仅用于dstMetadata路由插件的过滤
request.setMetadata(Map<String, String> metadata);
// 可选，设置元数据路由兜底措施
// 当前支持的元数据路由兜底措施如下
// - 默认不降级: METADATAFAILOVERNONE("metadataFailoverNone")
// - 降级返回所有节点: METADATAFAILOVERALL("metadataFailoverAll")
// - 返回不包含元数据路由key的节点: METADATAFAILOVERNOTKEY("metadataFailoverNoKey")
request.setMetadataFailoverType();
// 可选，对应自定义路由规则中请求标签中的方法(Method)
request.setMethod(String method);

// 如果需要走 Hash 负载均衡的话，需要设置
Criteria criteria = new Criteria();
request.setCriteria(criteria);

// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getOneInstance(request);

如何基于 polaris-java 客户端完成一个服务发现的程序

示例工程项目