这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

使用 Java SDK

1 - 注册发现

引入依赖

修改应用根目录下的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、被熔断的实例。

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 客户端完成一个服务发现的程序

2 - 动态路由

引入依赖

修改应用根目录下的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.RouterAPIFactory, 使用 RouterAPIFactory 中的方法进行构造一个 RouterAPI SDK 实例

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

public static void main(String[] args) throws Exception {
    RouterAPI routerAPI = RouterAPIFactory.createRouterAPI();
}

注册请求体

ProcessRoutersRequest request = new ProcessRoutersRequest();/
// 被调服务命名空间
request.setNamespace();
// 被调服务名称
request.setService();
// 可选，对应自定义路由规则中请求标签中的方法(Method)
request.setMethod();
// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setSourceService(serviceInfo);
// 设置待参与路由的目标实例
request.setDstInstances();

ProcessRoutersRequest.RouterNamesGroup group = new ProcessRoutersRequest.RouterNamesGroup();
// 设置前置路由
group.setBeforeRouters();
// 设置业务路由
group.setCoreRouters();
// 设置后置路由
group.setAfterRouters();
// 可选，设置路由插件执行链
// 当前支持的路由插件类型如下
// - 就近路由: nearByRoute
// - 自定义路由: ruleRouter
// - 元数据路由: metadataRoute
request.setRouters();

执行服务路由

你在初始化完 ProcessRoutersRequest 结构体后，只需要调用 RouterAPI.processRouters 方法即可完成服务路由

ProcessRoutersResponse resp = routerAPI.processRouters(registerRequest)

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

3 - 负载均衡

引入依赖

修改应用根目录下的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.RouterAPIFactory, 使用 RouterAPIFactory 中的方法进行构造一个 RouterAPI SDK 实例

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

public static void main(String[] args) throws Exception {
    RouterAPI routerAPI = RouterAPIFactory.createRouterAPI();
}

负载均衡

public class Criteria {
    // 一致性hash的key
    private String hashKey;
}

ProcessLoadBalanceRequest request = new ProcessLoadBalanceRequest();
// 设置需要参与负载均衡的服务实例
request.setDstInstances(ServiceInstances dstInstances);
// 设置负载均衡策略
// 当前支持的负载均衡策略如下
// - 权重随机负载均衡: weightedRandom
// - 权重一致性负载均衡: ringHash
request.setLbPolicy(String lbPolicy);

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

执行服务负载均衡

你在使用 ConsumerAPI.getAllInstances 或者 ConsumerAPI.getInstances 获取到服务实例列表后，完成 ProcessLoadBalanceRequest 初始化，只需要调用 RouterAPI.processLoadBalance 方法即可完成负载均衡

ProcessLoadBalanceResponse resp = routerAPI.processLoadBalance(request)

如何基于 polaris-java 客户端完成一个服务负载均衡的程序

4 - 熔断降级

熔断整个服务

配置熔断规则

配置服务熔断规则，针对default命名空间下所有的服务，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对服务进行熔断。

使用SDK进行熔断判断

方法说明

北极星Java SDK提供以下熔断相关的方法，所有的方法都在com.tencent.polaris.circuitbreak.api.CircuitBreakAPI接口中提供。

  • check：检查资源是否可被调用，并对资源获取调用申请。对于半开的资源，如果半开的调用配额申请成功，返回true，否则返回false。
  • report：该方法供用户在资源调用完成后，上报调用的结果，包括返回码、时延等信息，供熔断逻辑判断。
  • makeFunctionalDecorator：创建一个函数调用装饰器FunctionalDecorator，装饰器可以对Java的函数接口进行装饰。装饰后的逻辑，会在函数逻辑调用前，先通过check方法检查资源是否可被调用，如果不能被调用，会抛出资源熔断异常（CallAbortedException）。调用完成后，会通过report接口上报本次调用结果。FunctionalDecorator包含以下方法：
    • decorateSupplier：对函数接口Supplier进行封装。
    • decorateConsumer：对函数接口Consumer进行封装。
    • decorateFunction：对函数Function进行封装。
    • decoratePredicate：对函数接口Predicate进行封装。

使用示例

// 创建CircuitBreakAPI实例
CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();

// 通过传入服务名(testService1)和命名空间(default)，创建FunctionalDecorator
FunctionalDecoratorRequest makeDecoratorRequest = new FunctionalDecoratorRequest();
        makeDecoratorRequest.setService(new ServiceKey("default", "testService1"));
FunctionalDecorator decorator = circuitBreakAPI.makeFunctionalDecorator(makeDecoratorRequest);

// 封装函数接口
Consumer<Integer> integerConsumer = decorator.decorateConsumer(new Consumer<Integer>() {
    @Override
    public void accept(Integer object) {
      // 执行服务调用...
    }
});

// 通过执行函数接口，进行服务调用
// 在调用过程中，如果出现熔断，会抛出CallAbortedException异常
for (int i = 0; i < 500; i++) {
    try {
       integerConsumer.accept(i);
    } catch(CallAbortedException e) {
       e.printStackTrace();
    }
}

样例地址

Github地址

熔断单个接口

配置熔断规则

配置接口熔断规则，针对default命名空间所有服务的foo接口，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对接口进行熔断。

使用SDK进行熔断判断

熔断所使用的SDK接口及方法与服务级熔断相同，这里不再重复介绍。

使用示例

// 创建CircuitBreakAPI实例
CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();

// 通过传入服务名(testService1)、命名空间(default)和方法名(foo)，创建FunctionalDecorator
FunctionalDecoratorRequest makeDecoratorRequest = new FunctionalDecoratorRequest();
makeDecoratorRequest.setService(new ServiceKey("default", "testService1"));
makeDecoratorRequest.setMethod("foo");
FunctionalDecorator decorator = circuitBreakAPI.makeFunctionalDecorator(makeDecoratorRequest);

// 封装函数接口
Consumer<Integer> integerConsumer = decorator.decorateConsumer(new Consumer<Integer>() {
    @Override
    public void accept(Integer object) {
      // 执行服务接口调用...
    }
});

// 通过执行函数接口，进行服务调用
// 在调用过程中，如果出现熔断，会抛出CallAbortedException异常
for (int i = 0; i < 500; i++) {
    try {
       integerConsumer.accept(i);
    } catch(CallAbortedException e) {
       e.printStackTrace();
    }
}

样例地址

Github地址

熔断单个实例

配置熔断规则

配置实例熔断规则，针对default命名空间下所有的服务实例，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，每个实例的错误率是单独统计的，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对被调实例（IP:PORT）进行熔断。

使用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>

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

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

配置北极星服务端地址

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

global:
  serverConnector:
    # 北极星服务端地址，端口为8091
    addresses:
      - 127.0.0.1:8091

执行服务路由

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


public static void main(String[] args) throws Exception {
    CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();
    ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
    // 执行服务路由，筛选出单个实例，在这个过程中，会自动剔除熔断的实例
    GetOneInstanceRequest getOneInstanceRequest = new GetOneInstanceRequest();
    getOneInstanceRequest.setNamespace("default");
    getOneInstanceRequest.setService("testService1");
    InstancesResponse oneInstance = consumerAPI.getOneInstance(getOneInstanceRequest);
    Instance targetInstance = oneInstance.getInstances()[0];
    // 执行服务调用 --- 伪代码
    httpResult, delay = rpc(targetInstance.host, targetInstance.port, body);

    // invoke rpc call with targetInstance
    InstanceResource instanceResource = new InstanceResource(new ServiceKey(namespace, service),
            targetInstance.getHost(), targetInstance.getPort(), sourceService.getServiceKey());
    circuitBreakAPI.report(new ResourceStat(instanceResource, httpResult.code, delay));
}

样例地址

Github地址

启用主动探测

业务往往会存在高峰期和低峰期，低峰期流量比较少，不足以触发熔断，会出现当部分实例出现数据不可达的问题时，没法及时发现，导致高峰期到来时出现故障。

主动探测可以解决这个问题，启用主动探测后，主调方会定时根据探测规则，对被调实例进行探测，探测结果可作为熔断的判断依据，可实现对故障资源的快速熔断。

配置主动探测规则

配置一个主动探测规则，对服务（名为testService1，命名空间为default）进行探测。探测使用的协议是HTTP协议，由于服务开启了鉴权，因此探测时需要传入鉴权头。

注意：主动探测的规则，服务名可以选择全部服务，则规则针对全部服务生效。如果需要针对只接口进行探测，则可以在接口字段中填入对应的接口名。

在熔断规则中开启主动探测

需要在熔断规则中开启探测，这样才可以把探测结果用于熔断。

5 - 访问限流

引入依赖

修改应用根目录下的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.ratelimit.factory, 使用 LimitAPIFactory 中的方法进行构造一个 ProviderAPI SDK 实例

import com.tencent.polaris.ratelimit.factory.LimitAPIFactory;


public static void main(String[] args) throws Exception {
    LimitAPI limitAPI = LimitAPIFactory.createLimitAPI();
}

请求配额

QuotaRequest quotaRequest = new QuotaRequest();
// 设置需要进行限流的服务信息：设置命名空间信息
quotaRequest.setNamespace(String namespace);
// 设置需要进行限流的服务信息：设置服务名称信息
quotaRequest.setService(String service);
// 设置本次被调用的方法信息
quotaRequest.setMethod(String method);
// 设置本次的请求标签
quotaRequest.setArguments(Set<Argument> arguments)
// 设置需要申请的请求配额数量
quotaRequest.setCount(1);

发起配额申请请求

你在初始化完 QuotaRequest 结构体后，只需要调用 LimitAPI.getQuota 方法即可完成服务限流

QuotaResponse resp = limitAPI.getQuota(registerRequest)

分布式限流使用

如果要使用分布式限流，请先确保已经部署了北极星分布式限流 server

部署完后确认北极星控制台存在服务 命名空间: Polaris, 服务名: polaris.limiter。

确认完毕后，调整 polaris.yml 配置文件，在控制台配置分布式限流规则，SDK 仍然使用 QuotaResponse resp = limitAPI.getQuota(registerRequest) 即可。

provider:
  rateLimit:
    enable: true
	limiterNamespace: Polaris
	limiterService: polaris.limiter

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

6 - 配置管理

引入依赖

修改应用根目录下的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.configuration.factory, 使用 ConfigFileServiceFactory 中的方法进行构造一个 ConfigFileService SDK 实例

import com.tencent.polaris.configuration.factory.ConfigFileServiceFactory;

public static void main(String[] args) throws Exception {
    ConfigFileService configFileService = ConfigFileServiceFactory.createConfigFileService();
}

配置文件读取操作

// 获取特定远程的配置文件
ConfigFile configFile = configFileService.getConfigFile(String namespace, String fileGroup, String fileName);
System.out.println(configFile.getContent());

对配置文件发起监听

//获取配置文件
ConfigFile configFile = configFileService.getConfigFile(namespace, fileGroup, fileName);
//添加变更监听器
configFile.addChangeListener(new ConfigFileChangeListener() {
	@Override
	public void onChange(ConfigFileChangeEvent event) {
	}
});

查询加密配置

需要更新 polaris-java 的版本至 v1.13.0 +

// 获取特定远程的配置文件
ConfigFile getConfigFile(String namespace, String fileGroup, String fileName);

// 获取特定远程的配置文件
ConfigFile getConfigFile(ConfigFileMetadata configFileMetadata);

调整 polaris.yml 配置文件

# 配置中心默认配置
config:
  # 配置过滤器
  configFilter:
    enable: true
    chain:
      # 启用配置解密插件
      - crypto
    plugin:
      crypto:
        # 配置解密插件的算法插件类型
        type: AES

监听配置分组下的已发布文件列表变化

需要更新 polaris-java 的版本至 v1.14.0 及以上版本, 获取到目标配置分组后, 调用配置分组的 addChangeListener 方法监听改配置分组下已发布配置文件列表的变化

ConfigFileGroup configFileGroup = configFileService.getConfigFileGroup(namespace, fileGroup);
if (configFileGroup != null) {
    configFileGroup.addChangeListener(new ConfigFileGroupChangeListener() {
        @Override
        public void onChange(ConfigFileGroupChangedEvent event) {
            Utils.print(event.toString());
        }
    });
}

ConfigFileGroupChangedEvent 结构体的具体信息

public class ConfigFileGroupChangedEvent {
    // 配置分组自身元数据信息
    private final ConfigFileGroupMetadata configFileGroupMetadata;
    // 当前配置分组下的最新已发布的配置文件列表
    private final List<ConfigFileMetadata> configFileMetadataList;

    public ConfigFileGroupChangedEvent(ConfigFileGroupMetadata configFileGroupMetadata, List<ConfigFileMetadata> configFileMetadataList) {
        this.configFileGroupMetadata = configFileGroupMetadata;
        this.configFileMetadataList = configFileMetadataList;
    }

    public ConfigFileGroupMetadata getConfigFileGroupMetadata() {
        return configFileGroupMetadata;
    }

    public List<ConfigFileMetadata> getConfigFileMetadataList() {
        return configFileMetadataList;
    }

    @Override
    public String toString() {
        return "ConfigFileGroupChangedEvent{" +
                "configFileGroupMetadata=" + configFileGroupMetadata +
                ", configFileMetadataList=" + configFileMetadataList +
                '}';
    }
}

配置文件修改操作

使用 ConfigFileServicePublishFactory 中的方法进行构造一个 ConfigFilePublishService SDK 实例

import com.tencent.polaris.configuration.factory.ConfigFileServicePublishFactory;

public static void main(String[] args) throws Exception {
    ConfigFilePublishService configFilePublishService = ConfigFileServicePublishFactory.createConfigFilePublishService();
}

操作配置文件的方法

// 创建配置文件
void createConfigFile(String namespace, String fileGroup, String fileName, String content);

// 创建配置文件
void createConfigFile(ConfigFileMetadata configFileMetadata, String content);

// 修改配置文件
void updateConfigFile(String namespace, String fileGroup, String fileName, String content);

// 修改配置文件
void updateConfigFile(ConfigFileMetadata configFileMetadata, String content);

// 发布配置文件
void releaseConfigFile(String namespace, String fileGroup, String fileName);

// 发布配置文件
void releaseConfigFile(ConfigFileMetadata configFileMetadata);

相关示例工程代码

7 - 可观测性

引入依赖

修改应用根目录下的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 配置详细

通过 prometheus pull 模式上报监控数据
global:
  #描述: 监控及日志数据上报相关配置
  statReporter:
    #描述: 是否启用上报
    enable: true
    plugin:
      prometheus:
        type: pull
        #描述: 设置 prometheus http-server 的监听端口
        #类型:int
        #默认值: 28080
        #如果设置为负数，则不会开启默认的http-server，如果设置为0，则随机选择一个可用端口进行启动 http-server
        port: 28080
        #描述: 设置 prometheus http-server 的拉取path
        #类型:string
        #默认值: /metric
        path: /metric
通过 pushgateway push 模式上报监控数据
global:
  #描述: 监控及日志数据上报相关配置
  statReporter:
    #描述: 是否启用上报
    enable: true
    plugin:
      prometheus:
        type: push
        #描述: 设置 pushgateway 的地址, 仅 type == push 时生效
        #类型:string
        address: 127.0.0.1:9091
        #描述:设置metric数据推送到pushgateway的执行周期, 仅 type == push 时生效
        #类型:string
        #格式:^\d+(s|m|h)$
        #范围:[1s:...]
        #默认值:10s
        pushInterval: 10s

通过代码开启监控上报

通过 prometheus pull 模式上报监控数据
ConfigurationImpl configuration = (ConfigurationImpl) ConfigAPIFactory
				.defaultConfig(ConfigProvider.DEFAULT_CONFIG);
configuration.getGlobal().getStatReporter().setEnable(true);
PrometheusHandlerConfig prometheusHandlerConfig = configuration.getGlobal().getStatReporter()
				.getPluginConfig("prometheus", PrometheusHandlerConfig.class);
prometheusHandlerConfig.setPort(28080);
prometheusHandlerConfig.setPath("/metrics");
configuration.getGlobal().getStatReporter()
		.setPluginConfig("prometheus", prometheusHandlerConfig);
通过 pushgateway push 模式上报监控数据
ConfigurationImpl configuration = (ConfigurationImpl) ConfigAPIFactory
				.defaultConfig(ConfigProvider.DEFAULT_CONFIG);
configuration.getGlobal().getStatReporter().setEnable(true);
PrometheusPushHandlerConfig prometheusHandlerConfig = configuration.getGlobal().getStatReporter()
		.getPluginConfig("prometheus", PrometheusPushHandlerConfig.class);
prometheusHandlerConfig.setType("push");
prometheusHandlerConfig.setAddress("127.0.0.1:9091");
prometheusHandlerConfig.setPushInterval(30 * 1000L);
configuration.getGlobal().getStatReporter()
		.setPluginConfig("prometheus", prometheusHandlerConfig);

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();
}

服务调用结果

public enum RetStatus {
    // 服务调用成功
    RetSuccess,
    // 服务调用失败
    RetFail,
    // 服务调用超时
    RetTimeout,
}

ServiceCallResult result = new ServiceCallResult();
// 设置被调服务所在命名空间
result.setNamespace(String namespace);
// 设置被调服务的服务信息
result.setService(String service);
// 设置被调实例
result.setInstance(Instance instance);
// 设置本次请求的响应码
result.setRetCode(String code);
// 设置本次请求的耗时
result.setDelay(String delay);
// 设置本次请求的结果状态
result.setRetStatus(RetStatus status);
// 设置本次请求的请求标签，格式为 key=value;key=value;
result.setLabels(String labels);
// 设置本次请求调用的方法
result.setMethod(String method);

上报请求调用结果

你在根据请求调用情况对 ServiceCallResult 结构体完成初始化后，只需要调用 ConsumerAPI.updateServiceCallResult 方法即可完成请求调用结果上报。SDK 内部会根据上报的调用结果信息，将其转换为相应的流量调用指标数据，上报至 prometheus。

consumerAPI.updateServiceCallResult(ServiceCallResult)

8 - 二次寻址

引入依赖

修改应用根目录下的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 配置详细

修改 polaris.yml 开启二次寻址

global:
  system:
    discoverCluster:
      namespace: Polaris            # 设置服务注册发现集群服务所在的命名空间
      service: polaris.discover     # 设置服务注册发现集群服务的服务名称
      sameAsBuiltin: false
    healthCheckCluster:
      namespace: Polaris            # 设置健康检查集群服务所在的命名空间
      service: polaris.healthcheck  # 设置健康检查集群服务的服务名称
      sameAsBuiltin: false