操作场景
本文介绍在本地开发 Java 应用,通过 polaris-sdk 的方式接入 TSE 治理中心(北极星网格),并实现服务注册与发现。
前提条件
在开发前,请确保您已经下载并安装了 Java 和 Maven。
操作步骤
步骤1:引入北极星依赖
1. 引入 polaris sdk 依赖
修改应用根目录下的
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>
说明:
2. 引入 polaris starter
<dependencies><dependency><groupId>com.tencent.polaris</groupId><artifactId>polaris-all</artifactId></dependency></dependencies>
步骤2:添加北极星配置文件 polaris.yml
1. 在项目的 main/resources 目录下创建 polaris.yml 文件用于初始化 polaris-java SDK。
2. 在 polaris.yml 文件中配置应用名、polaris(北极星)服务端地址等信息。服务端地址查看详见:引擎管理 > 客户端访问地址。
global:serverConnectors:- id: polarisprotocol: grpcaddresses:# 地址需要替换成您创建的北极星引擎的客户端访问地址。- 127.0.0.1:8091#描述: 监控及日志数据上报相关配置statReporter:#描述: 是否启用上报enable: trueplugin:prometheus:type: push# 描述: 设置 pushgateway 的地址, 仅 type == push 时生效# 地址需要替换成您创建的北极星引擎的客户端访问地址。address: 127.0.0.1:9091#描述:设置metric数据推送到pushgateway的执行周期#范围:[1s:...],默认值:10spushInterval: 10s
步骤3:应用开发
1. 服务注册(服务生产者)
1.1 初始化 DiscoveryAPI 实例
import com.tencent.polaris.factory.api.DiscoveryAPIFactory;public static void main(String[] args) throws Exception {ProviderAPI providerAPI = DiscoveryAPIFactory.createProviderAPI();}
1.2 注册请求体,设置健康检查、metadata 等信息。
// InstanceRegisterRequest 注册服务请求type InstanceRegisterRequest struct {// 必选,服务名Service string// 必选,命名空间Namespace string// 必选,服务监听host,支持IPv6地址Host string// 必选,服务实例监听portPort int// 可选,资源访问Token,即用户/用户组访问凭据,仅当服务端开启客户端鉴权时才需配置ServiceToken string// 以下字段可选,默认nil表示客户端不配置,使用服务端配置// 服务协议Protocol *string// 服务权重,默认100,范围0-10000Weight *int// 实例提供服务版本号Version *string// 用户自定义metadata信息Metadata map[string]string// 该服务实例是否健康,默认健康Healthy *bool// 该服务实例是否隔离,默认不隔离Isolate *bool// 设置心跳健康检查ttl,单位为s,不填默认为5s,TTL的取值范围为 (0s, 60s]// 开启了心跳健康检查,客户端必须以TTL间隔上报心跳// 健康检查服务器3个TTL未受到心跳则将实例置为不健康TTL *int// Location 当前注册实例的地理位置信息,主要用于就近路由Location *Location// 可选,单次查询超时时间,默认直接获取全局的超时配置// 用户总最大超时时间为(1+RetryCount) * TimeoutTimeout *time.Duration// 可选,重试次数,默认直接获取全局的超时配置RetryCount *int}
说明:
1.3 发起注册请求
在初始化完
InstanceRegisterRequest
结构体后,只需要调用ProviderAPI.RegisterInstance
方法即可完成实例注册,并且 RegisterInstance
方法内部会自动维护实例的心跳上报。InstanceRegisterResponse registerResp = providerAPI.registerInstance(registerRequest)
2. 服务发现(服务消费者)
2.1 初始化 polaris sdk 实例
import com.tencent.polaris.factory.api.DiscoveryAPIFactory;public static void main(String[] args) throws Exception {ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();}
2.2 获取服务提供方的实例信息
北极星提供三种获取目标服务实例的方法:GetAllInstances、GetHealthyInstances、GetOneInstances,分别获取全部实例、健康实例和一个实例。详情如下:
(1)GetAllInstances
直接返回目标服务下的所有实例,包括不健康、隔离、权重为0、被熔断的实例,都会在返回的实例列表中。
GetAllInstancesRequest request = new GetAllInstancesRequest();// 设置服务命名空间request.setNamespace(String namespace);// 设置服务名称request.setService(String service);// 设置超时时间request.setTimeoutMs(long timeoutMs);// 调用 ConsumerAPI 执行该请求consumerAPI.getAllInstance(request);
(2)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);
(3)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);
步骤4:应用部署