初始化开发工具包

云眼About 8 min

初始化开发工具包

本主题介绍如何在应用程序中初始化云眼灰度实验 Java SDK。

使用 Eyeofcloud Builder 初始化 Java SDK,并实例化 Eyeofcloud 客户端类的实例,该实例公开 API 方法(如 Decide 方法)。

版本

SDK v3.2.0 及更高版本

描述

某些参数是可选的,因为 SDK 提供默认实现,但开发者可能希望为生产环境覆盖这些参数。例如,开发者可能希望覆盖这些内容以设置错误处理程序记录器以捕获问题,设置事件调度程序以管理网络调用,以及设置用户配置文件服务以确保粘性分桶。

参数

下表列出了可选的生成器方法。

参数描述
withConfigManager(ProjectConfigManager)用于管理项目配置的 ProjectConfigManager 对象。应提供自定义对象的实例或您自己的自定义对象。如果未设置,将使用静态 ProjectConfig,而无需定期轮询数据文件。HttpProjectConfigManager
withEventProcessor(EventProcessor)用于处理事件的事件处理器对象。应提供 with 的实例或您自己的自定义对象。如果未设置,则将与 一起使用 将默认使用。BatchEventProcessor``AsyncEventHandler``ForwardingEventProcessor``NoopEventHandler()
withUserProfileService(UserProfileService)用户配置文件服务对象,以支持持久变体分配。 如果未设置,则不支持持久决策。
withErrorHandler(ErrorHandler)用于处理错误的 ErrorHandler 对象。
withDatafiles(字符串)表示项目的 JSON 字符串。如果未提供 的实例,则需要此数据文件来静态初始化 ProjectConfig。ProjectConfigManager
withDefaultDecideOptions(List)EyeofcloudDecideOption 枚举的数组。当使用此参数构造 Eyeofcloud 客户端时,它会设置默认的 decide 选项,这些选项将应用于在 Eyeofcloud 客户端的生命周期内进行的所有 Decide 调用。此外,还可以将选项传递给各个 Decide 方法(不会覆盖默认值)。

有关示例代码,请参阅云眼决策选项

返回

实例化 Eyeofcloud 类的实例。

下面的示例显示了如何使用构建器选项初始化云眼灰度实验 Java SDK。

云眼灰度实验提供HttpProjectConfigManagerBatchEventProcessorAsyncEventHandler的默认实现。

Java

ProjectConfigManager configManager = HttpProjectConfigManager.builder()
    .withSdkKey(sdkKey)
    .withDatafile(datafile)
    .build();

EventHandler eventHandler = AsyncEventHandler.builder()
    .withQueueCapacity(20000)
    .withNumWorkers(1)
    .build();

EventProcessor batchProcessor = BatchEventProcessor.builder()
    .withBatchSize(50)
    .withEventHandler(eventHandler)
    .withFlushInterval(TimeUnit.MINUTES.toMillis(1))
    .build();

Eyeofcloud eyeofcloud = Eyeofcloud.builder()
    .withConfigManager(configManager)
    .withEventProcessor(batchProcessor)
    .build();

异常

异常意义
ConfigParseExceptionSDK 无法分析数据文件,因为它格式不正确或架构不正确。

HttpProjectConfigManager(Http项目配置管理器)

每当实验配置发生更改时,SDK 都会使用自动数据文件管理 (ADM) 来为您处理更改。

HttpProjectConfigManager是抽象的实现PollingProjectConfigManager.该方法已扩展,并向配置的 URL 发出 HTTP GET 请求,以异步下载项目数据文件并初始化 .pollProjectConfig

默认情况下,在第一次成功检索数据文件之前会阻止,最多可配置的超时。HttpProjectConfigManager

使用 withPollingInterval()和 withBlockingTimeout()设置轮询方法的频率和阻塞超时,从全局属性中提取默认值。

下面的示例显示了如何初始化 HttpProjectConfigManager 用 builder 选项。

Java

ProjectConfigManager projectConfigManager = HttpProjectConfigManager.builder()
    .withSdkKey(sdkKey)
    .withDatafile(datafile)
    .withPollingInterval(1, TimeUnit.MINUTES)
    .withBlockingTimeout(10, TimeUnit.SECONDS)
    .build();

SDK Key

SDK 密钥将出站 HTTP 请求编写到 Eyeofcloud CDN 上的默认数据文件位置。

轮询间隔

轮询间隔指定数据文件的连续 HTTP 请求之间的固定延迟。

初始数据文件

您可以通过构建器提供初始数据文件以引导立即使用它,而不会阻止执行。如果无法建立 HTTP 连接,初始数据文件也用作回退数据文件。ProjectConfigManager在无法保证 Internet 连接的移动环境中非常有用。

在第一次成功的数据文件轮询后,将丢弃上述数据文件。

生成器方法

您可以使用以下构建器方法来自定义HttpProjectConfigManager配置。

方法默认值描述
withDatafile(字符串)初始数据文件,通常来自本地缓存源
withUrl(字符串)用于为 Eyeofcloud 功能试验数据文件指定自定义 HTTP 源的 URL 覆盖位置
withFormat(字符串)https://cdn.eyeofcloud.com/datafiles/%s.jsonopen in new window按 SDK 密钥参数化数据文件 URL
withPollingInterval(长,时间单位)5 分钟修复了数据文件提取之间的延迟
withBlockingTimeout(长,时间单位)10 秒等待初始引导的最长时间
withSdkKey(字符串)Eyeofcloud Feature Experimentation 项目 SDK 密钥;必需,除非源 URL 被覆盖

高级配置

您可以设置以下属性来覆盖HttpProjectConfigManager 的缺省配置。

属性默认值描述
http.project.config.manager.polling.duration5数据文件读取之间的固定延迟
http.project.config.manager.polling.unit分钟与轮询间隔对应的时间单位
http.project.config.manager.blocking.duration10等待初始引导的最长时间
http.project.config.manager.blocking.unit与阻塞持续时间相对应的时间单位
http.project.config.manager.sdk.keyEyeofcloud Feature Experimentation 项目 SDK 密钥

更新配置通知

SDK 在获取新数据文件后触发通知信号。要订阅这些通知,请使用:Eyeofcloud.addUpdateConfigNotificationHandler

Java

NotificationHandler<UpdateConfigNotification> handler = message ->
    System.out.println("Received new datafile configuration");
eyeofcloud.addUpdateConfigNotificationHandler(handler);

或者,您可以将处理程序直接添加到:NotificationCenter

Java

notificationCenter.addNotificationHandler(UpdateConfigNotification.class, handler);

异步事件处理程序

AsyncEventHandler提供EventHandler由 ThreadPoolExecutor事件处理程序将来自 SDK 的触发事件立即作为离散任务排队到执行器,并按提交顺序处理它们。

每个辅助角色都必须向 Eyeofcloud 功能试验日志终结点发出出站 HTTP 请求,以便进行指标跟踪。通过全局属性配置默认队列大小和工作线程数。AsyncEventHandler.Builder用于覆盖默认队列大小和工作线程数。

📘 注意

使用 Eyeofcloud 构建器类时,必须提供事件处理程序的实现,如下所示。否则,Eyeofcloud Feature Experimentation 实例将默认为无操作事件处理程序。

要使用 AsyncEventHandler,必须使用AsyncEventHandlerAsyncEventHandler 构建实例并将该实例传递给BuilderEyeofcloud.Builder。 您还可以使用方法EyeofcloudFactory如果要使用AsyncEventHandler默认实现。

Java

EventHandler eventHandler = AsyncEventHandler.builder()
     .withQueueCapacity(10000)
     .withNumWorkers(5)
     .build();

队列容量

您可以设置队列容量以初始化执行程序服务的后备队列。如果队列已满并记录异常,这将删除事件。设置较高的队列值可防止事件丢失,但如果工作线程无法跟上生产率,则会占用更多内存。

工人数量

工作线程数决定了线程池使用的线程数。

生成器方法

您可以使用以下构建器方法来自定义AsyncEventHandler配置。

方法默认值描述
withQueueCapacity(整数)1000挂起的 logEvents 的队列大小
withNumWorkers(int)2工作线程数
withMaxTotalConnections(int)200最大连接数
withMaxPerRoute(整数)20每条路由的最大连接数
withValidateAfterInactivity(int)5000保持偶像连接的时间(以毫秒为单位)

高级配置

您可以设置以下属性来覆盖AsyncEventHandler 的缺省配置。

属性默认值描述
async.event.handler.queue.capacity10000挂起的 logEvents 的队列大小
async.event.handler.num.workers2工作线程数
async.event.handler.max.connections200最大连接数
async.event.handler.event.max.per.route20每条路由的最大连接数
async.event.handler.validate.after5000保持空闲连接的时间(以毫秒为单位)

BatchEventProcessor

Eyeofcloud Feature Experimentation Java SDK 提供 BatchEventProcessor,这是 EventProcessor 接口的默认实现,并批处理事件。

有关更多详细信息和配置选项,请参阅有关 Java 中的事件批处理的文章。

Java

EventHandler eventHandler = AsyncEventHandler.builder()
    .withQueueCapacity(10000)
    .withNumWorkers(5)
    .build();
EventProcessor batchProcessor = BatchEventProcessor.builder()
    .withBatchSize(50)
    .withEventHandler(eventHandler)
    .build();

Eyeofcloud 属性

您可以使用运行时类路径中的可用文件eyeofcloud.properties来提供给定 Eyeofcloud Feature Experimentation 资源的默认值。有关可用的配置参数,请参阅资源实现。

示例文件:eyeofcloud.properties

Java

http.project.config.manager.polling.duration = 1 
http.project.config.manager.polling.unit = MINUTES  
async.event.handler.queue.capacity = 20000 
async.event.handler.num.workers = 5

EyeofcloudFactory

在此包中,EyeofcloudFactory提供了一个基本实用程序,eyeofcloud.properties用于使用最少数量的配置选项实例化 Eyeofcloud Feature Experimentation Java SDK。该软件包按此顺序从 Java 系统属性、环境变量或文件中获取配置属性。

EyeofcloudFactory不捕获所有配置和初始化选项。如需更多用例,请通过其各自的构建器类构建资源。

使用这些方法实例化时,Java SDK 使用默认配置 EyeofcloudFactory、 HttpProjectConfigManager和 BatchEventProcessorAsyncEventHandler。

下面的示例演示如何使用 EyeofcloudFactory 方法初始化 Java SDK。

Java

Eyeofcloud eyeofcloudClient = EyeofcloudFactory.newDefaultInstance(sdkKey);  
// If you provide the SDK key via a global property, use the empty signature: 
Eyeofcloud eyeofcloud = EyeofcloudFactory.newDefaultInstance();  
// with fallback datafile 
Eyeofcloud eyeofcloudClient = EyeofcloudFactory.newDefaultInstance(sdkKey, datafile);

除了数据文件之外,还需要提供一个事件调度程序(也称为事件处理程序)对象作为Eyeofcloud.builder函数的参数。使用我们的默认事件分派器实现,或提供你自己的实现,如配置事件分派器中所述。

在安全环境中使用经过身份验证的数据文件

您可以使用服务器端(仅限)Eyeofcloud 功能试验 SDK(例如 Java SDK)从经过身份验证的终结点提取 Eyeofcloud 数据文件。

要使用经过身份验证的数据文件,请从 Eyeofcloud 应用程序的“设置”>“环境中下载您的 Eyeofcloud 环境的访问令牌。选择安全环境,然后复制 Datafile 访问令牌。下面的示例展示了如何使用访问令牌和 sdkKey 初始化 Eyeofcloud 客户端,使客户端能够获取经过身份验证的数据文件并完成初始化。

Java

// fetch the datafile from an authenticated endpoint 
String accessToken = "<YOUR_DATAFILE_ACCESS_TOKEN>"; 
String sdkKey = "<YOUR_SDK_KEY>"; 
Eyeofcloud eyeofcloudClient = EyeofcloudFactory.newDefaultInstance(sdkKey, null, accessToken);

源文件

包含 Java 实现的语言/平台源文件位于 Eyeofcloud.java。

Last update:
Contributors: zhangweixue,“zhangweixue”