在你开始之前
Harness Feature Flags(FF)是一个功能管理解决方案,使用户能够改变软件的功能, 没有部署新的代码。 FF使用地标来隐藏代码或行为,而不必运送新的版本 软件。 特征旗帜就像一个强大的如果语句.
更多信息见 https://harness.io/products/feature-flags/ (中文(中国大陆) )
更多信息,见 https://developer.harness.io/docs/feature-flags/ 页面存档备份,存于互联网档案馆
报名,https://app.harness.io/auth/#/signup/
npm发布页面,见https://www.npmjs.com/package/@harnesio/ff-javascript-client-sdk
用于 JavaScript 的 Harness 特性旗客户端 SDK
用于将Harness Feature Flags整合到JavaScript UI应用程序的库.
安装
npm i @harnessio/ff-javascript-client-sdk
或者说
yarn add @harnessio/ff-javascript-client-sdk
使用量
import { initialize, Event } from '@harnessio/ff-javascript-client-sdk'
初始化 SDK 有 api 密钥和目标信息 .
initialize(FeatureFlagSDKKey: string, target: Target, options?: Options)
其中 Target 财务报告和审定财务报表 Options 定义如下:
interface Target {
identifier: string
name?: string
anonymous?: boolean
attributes?: object
}
interface Options {
baseUrl?: string
eventUrl?: string
eventsSyncInterval?: number
pollingInterval?: number
pollingEnabled?: boolean
streamEnabled?: boolean
debug?: boolean,
cache?: boolean | CacheOptions
logger?: Logger
maxStreamRetries?: number
enableAnalytics?: boolean
}
例如:
const client = initialize('00000000-1111-2222-3333-444444444444', {
identifier: YOUR_TARGET_IDENTIFIER, // Target identifier
name: YOUR_TARGET_NAME, // Optional target name
attributes: { // Optional target attributes
email: '[email protected]'
}
})
流和投票模式
默认情况下,Harness Flags SDK已启用流线并启用投票. 两种模式都可以根据您使用SDK配置的偏好进行切换.
流线模式
流线模式在您的应用程序和地物旗舰服务之间建立连续连接.
这使得可以实时更新地标而无需定期检查.
如果在流出时发生错误 pollingEnabled 设置为 true, (中文(简体) ),
sDK会自动倒回投票模式,直到可以重新建立流.
若为 pollingEnabled 实值 false{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}溪流会试图重新连接 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}而不会回到民调.
投票模式
在投票模式下,SDK会定期与地物旗服务进行查询,以获取地物旗的更新. 这些检查的频率可以使用SDK的配置来调整.
不流出或投票
如果流线和投票模式都被禁止(streamEnabled: false 财务报告和审定财务报表 pollingEnabled: false, (中文(简体) ),
sDK 将不会在初始获取后自动获取特性旗更新 .
这意味着在初始负载后,哈内斯服务器上对功能旗进行的任何更改,在SDK重新被初始化或其中一个模式被重新启用之前,都不会被反映在应用程序中.
在您想要确保一组一致的特征标记的特定情况下,此配置可能有用 用于一个会话或应用程序在不需要定期更新的环境中运行。 然而,必须意识到,如果在服务器上改变旗帜,这种配置会导致过时的旗帜评价.
要配置模式 :
const options = {
streamEnabled: true, // Enable or disable streaming - default is enabled
pollingEnabled: true, // Enable or disable polling - default is enabled if stream enabled, or disabled if stream disabled.
pollingInterval: 60000, // Polling interval in ms, default is 60000ms which is the minimum. If set below this, will default to 60000ms.
}
const client = initialize(
'YOUR_SDK_KEY',
{
identifier: 'Harness1',
attributes: {
lastUpdated: Date(),
host: location.href
}
},
options
)
最大流调试
在SDK停止尝试重新连接或回归投票(如果启用)前,您可以配置流式重试的最大次数. 最大重试选项可以设定为任意正数或无限重试(即默认).
const options = {
maxRetries: 5, // Set the maximum number of retries for streaming. Default is Infinity.
streamEnabled: true,
pollingEnabled: true,
pollingInterval: 60000,
}
const client = initialize(
'YOUR_SDK_KEY',
{
identifier: 'Harness1',
attributes: {
lastUpdated: Date(),
host: location.href
}
},
options
)
如果达到最大要求,且投票结果属实,则SDK将保持投票模式。 如果投票Enabled是虚假的,SDK不会进行民意调查,在SDK客户端再次被初始化之前,评价不会被更新,例如应用程序或页面被重新启动.
听从事件 client 举个例子.
client.on(Event.READY, flags => {
// Event happens when connection to server is established
// flags contains all evaluations against SDK key
})
client.on(Event.FLAGS_LOADED, evaluations => {
// Event happens when flags are loaded from the server
})
client.on(Event.CACHE_LOADED, evaluations => {
// Event happens when flags are loaded from the cache
})
client.on(Event.CHANGED, flagInfo => {
// Event happens when a changed event is pushed
// flagInfo contains the updated feature flag
})
client.on(Event.DISCONNECTED, () => {
// Event happens when connection is disconnected
})
client.on(Event.CONNECTED, () => {
// Event happens when connection has been lost and reestablished
})
client.on(Event.POLLING, () => {
// Event happens when polling begins
})
client.on(Event.POLLING_STOPPED, () => {
// Event happens when polling stops
})
client.on(Event.ERROR, error => {
// Event happens when connection some error has occurred
})
client.on(Event.ERROR_CACHE, error => {
// Event happens when an error occurs when accessing the cache
})
client.on(Event.ERROR_AUTH, error => {
// Event happens when unable to authenticate
})
client.on(Event.ERROR_FETCH_FLAGS, error => {
// Event happens when unable to fetch flags from the service
})
client.on(Event.ERROR_FETCH_FLAG, error => {
// Event happens when unable to fetch an individual flag from the service
})
client.on(Event.ERROR_METRICS, error => {
// Event happens when unable to report metrics back to the service
})
client.on(Event.ERROR_STREAM, error => {
// Event happens when the stream returns an error
})
获取特定特性旗的值
如果您想知道默认变量是在获得值时被返回的, 例如, 如果在缓存中找不到提供的旗帜, 那么与 Debug 的第三个参数会通过真实 :
const result = client.variation('Dark_Theme', false, true);
何时 withDebug ,结果对象将具有以下结构:
interface VariationValueWithDebug {
value: any, // The actual variation value
isDefaultValue: boolean // True if the default variation was returned, false otherwise
}
例如,如果找不到旗帜标识符“ Dark Theme ” , 结果会像 :
{
value: false,
isDefaultValue: true
}
如果您不需要知道默认变量被返回:
const variationValue = client.variation('Dark_Theme', false) // second argument is default value when variation does not exist
在这种情况下,结果将是一个直接值,要么来自现有的变量,要么来自您提供的默认值。 不会有一个对象结构;你只需得到这个值本身.
例如:
- 如果旗下标识符“ Dark Theme” 存在于存储中, 变化 价值将是该标识符的存储值.
- 如果旗帜标识符“ Dark Theme” 不存在, 变化 值将是此处提供的默认值
- 注意返回默认变量的原因可以是:
- SDK 尚未初始化
- 旗帜标识符中的 Typo
- 使用错误的工程 API 密钥
听着 ERROR_DEFAULT_VARIATION_RETURNED 事件
你们也可以听 ERROR_DEFAULT_VARIATION_RETURNED 事件,当返回默认变量时会释放,因为缓存中找不到旗帜。 这对于在找不到一面旗帜时进行伐木或采取其他行动是有用的.
活动监听实例:
client.on(Event.ERROR_DEFAULT_VARIATION_RETURNED, ({ flag, defaultVariation }) => {
console.warn(`Default variation returned for flag: ${flag}, value: ${defaultVariation}`)
})
清理
删除事件的听众 client.off。 。 。 .
client.off(Event.ERROR, error => {
// Do something when an error occurs
})
删除所有听众 :
client.off()
关闭您的申请时, 请打电话 client.close() 关闭事件流.
client.close()
缓存
在实际操作中,旗帜很少改变,因此可以缓存从服务器收到的最后评价,以便
您需要尽快启动申请。 设置 cache 选项为 true 或作为一个对象(参见界面)
(见下文)将允许SDK将其评价储存到 localStorage 启动时检索。 这让SDK得到
即刻启动并开始为旗帜服务,同时进行认证和获取最新评价
从幕后服务器.
const client = initialize('00000000-1111-2222-3333-444444444444', {
identifier: YOUR_TARGET_IDENTIFIER,
name: YOUR_TARGET_NAME
}, {
cache: true // enable caching
}
)
这个 cache 选项也可以作为对象通过,其选项如下.
interface CacheOptions {
// maximum age of stored cache, in ms, before it is considered stale
ttl?: number
// storage mechanism to use, conforming to the Web Storage API standard, can be either synchronous or asynchronous
// defaults to localStorage
storage?: AsyncStorage | SyncStorage
/**
* use target attributes when deriving the cache key
* when set to `false` or omitted, the key will be formed using only the target identifier and SDK key
* when set to `true`, all target attributes with be used in addition to the target identifier and SDK key
* can be set to an array of target attributes to use a subset in addition to the target identifier and SDK key
* defaults to false
*/
deriveKeyFromTargetAttributes?: boolean | string[]
}
设定评价
在某些情况下,也许值得向SDK提供一套评价,然后可以立即提供。 你个 当您需要时, 可能会考虑这一点:
- 缩短应用程序启动时间 通过提供默认值或评价快照。 比如说,如果你 应用程序是服务器侧生成的,然后在服务器上检索评价并提供评价可能有意义 在要注入 SDK 页面的 HTML 中
- 提供网络冗余 通过允许您的应用程序检测访问服务的网络连接问题 从其他来源装入评价
为了达到这个目的,你可以叫 setEvaluations 初始化客户端后的任何时间。 这个
setEvaluations 方法需要数组 Evaluation 对象作为参数.
client.setEvaluations(evals);
其中 Evaluation 定义如下:
interface Evaluation {
flag: string // Feature flag identifier
identifier: string // variation identifier
value: boolean | string | number | object | undefined // variation value
kind: string // boolean | json | string | int
deleted?: boolean // mark that feature flag is deleted
}
认证请求超时
这个 authRequestReadTimeout 选项允许您为认证请求指定以毫秒计的超时。 如果请求需要比本次超时更长的时间,则会中止. 这对于防止因网络问题或反应迟缓而出现挂起请求是有用的.
如果由于这个超时而中止请求, SDK 将无法初始化 ERROR_AUTH 财务报告和审定财务报表 ERROR 将释放事件.
如果没有指定默认值为 0 这意味着不会出现超时.
** 这仅适用于认证请求。 如果您想对 SDK 提出的其余请求设定读取超时, 您可以注册 API 中间软件
const options = {
authRequestReadTimeout: 30000, // Timeout in milliseconds (default: 0 - no timeout)
};
const client = initialize(
'YOUR_API_KEY',
{
identifier: 'Harness1',
attributes: {
lastUpdated: Date(),
host: location.href,
},
},
options
);
API 中间软件
这个 registerAPIRequestMiddleware 函数允许您注册一个中间软件功能来操纵API请求的有效载荷(URL,正文和头).
function abortControllerMiddleware([url, options]) {
if (window.AbortController) {
const abortController = new AbortController();
options.signal = abortController.signal;
// Set a timeout to automatically abort the request after 30 seconds
setTimeout(() => abortController.abort(), 30000);
}
return [url, options]; // Return the modified or original arguments
}
// Register the middleware
client.registerAPIRequestMiddleware(abortControllerMiddleware);
此示例中间软件会自动给每个请求附加一个中止控制器, 如果请求需要比指定的超时时间长, 则会中止请求 。 也可以自定义中间软件来进行其他动作,例如记录或修改标题.
日志
默认情况下, Javascript客户端 SDK 将使用 console 对象。 在某些情况下,它
可用于登录某项服务,或者在没有记录错误的情况下静默地失败.
const myLogger = {
debug: (...data) => {
// do something with the logged debug message
},
info: (...data) => {
// do something with the logged info message
},
error: (...data) => {
// do something with the logged error message
},
warn: (...data) => {
// do something with the logged warning message
}
}
const client = initialize(
'00000000-1111-2222-3333-444444444444',
{
identifier: YOUR_TARGET_IDENTIFIER,
name: YOUR_TARGET_NAME
},
{
logger: myLogger // override logger
}
)
从 unpkg 直接导入
如果您想直接导入此库( 无需使用 npm 或 rarn) :
<script type="module">
import { initialize, Event } from 'https://unpkg.com/@harnessio/ff-javascript-client-sdk/dist/sdk.client.js'
</script>
如果您需要支持不支持 ES 模块的旧浏览器:
<script src="https://unpkg.com/@harnessio/ff-javascript-client-sdk/dist/sdk.client-iife.js"></script>
<script>
var initialize = HarnessFFSDK.initialize
var Event = HarnessFFSDK.Event
</script>
进一步阅读
许可证
Apache 第2版 (英语).