翻转客户端JS
这个 flipt-client-js 库中包含用于 Flipt 的 JavaScript/ TypeScript 客户端 客户端评价 在 Web 和 Node.js 环境中。 它支持:
- 节点.js
- 浏览器
- 边缘函数(Vercel Edge, Cloudflare 工人等)
- 网络工人
安装
[注] 节点.js所建需要节点.js 20或更晚.
npm install @flipt-io/flipt-client-js
使用量
import { FliptClient } from '@flipt-io/flipt-client-js';
const client = await FliptClient.init({
namespace: 'default',
url: 'http://localhost:8080',
authentication: {
clientToken: 'secret'
}
});
const variant = client.evaluateVariant({
flagKey: 'flag1',
entityId: 'someentity',
context: {
fizz: 'buzz'
}
});
console.log(variant);
导入类型
所有类型都可以从主包导出 :
import type { Flag, ClientOptions, EvaluationRequest } from '@flipt-io/flipt-client-js';
或者,您也可以从专用程序导入类型 /types 子路径 :
import type { Flag, ClientOptions, EvaluationRequest } from '@flipt-io/flipt-client-js/types';
初始化参数
这个 FliptClient 构造器接受下列可选参数:
options: 实例ClientOptions类型,用于支持客户端的若干选项。 其结构是:environment: 评价旗帜时所用的环境(Flipt v2)。 如果不提供,客户端将默认为default环境.namespace: 获取旗下状态的命名空间 。 如果不提供,客户端将默认为default名称空间.url: 上游翻转实例的 URL。 如果不提供,客户端将默认为http://localhost:8080。 。 。 .updateInterval数字 : 只有节点.js 获取新旗帜状态的间隔( 以秒计) 。 如果不提供,客户端将默认为120秒.fetchMode:客户端如何接收旗帜状态更新 :FetchMode.Polling(违约)或FetchMode.Streaming。见 流线。 。 。 .logger: 一个可选的日志( )debug, (中文(简体) ),info, (中文(简体) ),warn, (中文(简体) ),error用于诸如流出事件等诊断. 默认禁用日志 .authentication: 与上游翻转实例通信时使用的认证策略。 如果不提供,客户端将默认为没有认证. 见 认证 用于提供更多信息.reference编号: 参考文献 用于获取旗帜状态。 如果不提供参考文献,则不使用参考文献.snapshot: 基数64- 编码快照返回client.getSnapshot()提供时errorStrategy: ErrorStrategy.Fallback,客户端可以在下线时初始化,并在网络可用时从Flipt中刷新.fetcher执行 获取器 界面,用于请求旗帜状态时。 如果没有提供,则使用浏览器的默认取取器fetchAPI 密码 将被使用.errorStrategy: 获取旗帜状态时所用的错误策略 。 如果不提供,客户端将默认失败. 见 错误策略 用于提供更多信息.hook:用于评价前后回调的钩子执行. 见 钩子 用于提供更多信息.onStateUpdate:一个没有参数的函数,在客户端应用已更改的旗帜状态后调用. 见 状态更新听众。 。 。 .
认证
这个 FliptClient 支持下列认证战略:
错误策略
客户 errorStrategy 选项支持以下错误策略:
fail: 如果无法获取旗下状态, 客户端会出错 。 这是默认行为.fallback:客户端将保持最后已知的好状态,并在出错时使用该状态进行评价.
抓图
客户端支持人工快照旗下状态. 当一个应用程序在Flipt可以到达之前启动时, 这一点是有用的 。 SDK不为您写入本地存储,因为浏览器,Node.js,边缘,以及工人环境存储数据的方式不同.
使用 getSnapshot() 将当前状态导出, 保存在您的应用程序所喜欢的地方, 并传回为 snapshot 在下一个启动.
import { ErrorStrategy, FliptClient } from '@flipt-io/flipt-client-js';
const snapshot = localStorage.getItem('fliptSnapshot') ?? undefined;
const client = await FliptClient.init({
namespace: 'default',
url: 'https://your-flipt-instance.com',
snapshot,
errorStrategy: ErrorStrategy.Fallback
});
localStorage.setItem('fliptSnapshot', client.getSnapshot());
如果Flipt在初始化过程中可以被达到,则新鲜的服务器状态取代所提供的快照. 如果翻转是无法到达的 ErrorStrategy.Fallback 设置,客户端使用提供的快照进行评估.
自定义获取器
这个 FliptClient 支持自定义获取器。 这允许您从自定义源获取旗下状态, 或者覆盖 HTTP 头 .
取取器可以传递给 FliptClient 初始化函数 .
const client = await FliptClient.init({
namespace: 'default',
url: 'http://localhost:8080',
authentication: {
clientToken
},
fetcher: customFetcher
});
获取器是一个需要可选的函数 IFetcherOpts 参数并返回 a Promise 决心 Response 对象.
钩子
这个 FliptClient 支持允许您在旗帜评价前后执行自定义代码的钩子。 这对伐木、测量采集或其他可观察模式有用.
Hook 接口
要使用钩子,请执行 Hook 接口.
示例:记录钩
import { FliptClient } from '@flipt-io/flipt-client-js';
class LoggingHook {
before(data: { flagKey: string }) {
console.log(`Evaluating flag: ${data.flagKey}`);
}
after(data: {
flagKey: string;
flagType: string;
value: string;
reason: string;
segmentKeys: string[];
}) {
console.log(
`Flag ${data.flagKey} evaluated: type=${data.flagType}, value=${data.value}, reason=${data.reason}`
);
}
}
const client = await FliptClient.init({
namespace: 'default',
url: 'http://localhost:8080',
hook: new LoggingHook()
});
const result = client.evaluateVariant({
flagKey: 'my-flag',
entityId: 'user-123',
context: { environment: 'production' }
});
console.log(result);
钩子要求所有的评价方法:
evaluateVariant:每次评价一次evaluateBoolean:每次评价一次evaluateBatch:在每次请求之前发出一次电话,在每次成功答复之后发出一次电话
说明: 虎克是可选的。 如果没有钩子,评价通常不召回.
州管理层
这个 FliptClient 类从 Flipt 实例中拉出旗帜状态 url b. 《公约》 options 在即时状态下的对象.
为了更新旗下状态,你可以打电话给 refresh 方法 FliptClient 课.
[注] 这个
refresh方法返回布尔表示国旗状态是否改变.
// Refresh the flag state
let changed = await client.refresh();
if (changed) {
// Do something
}
自动更新( 只有节点js)
这个 FliptClient 类支持自动刷新旗帜状态.
要自动刷新,你可以通过 updateInterval 选项 FliptClient 初始化函数 。 盖子下方使用计时器在正常间隔取取取新国旗状态.
[注] 这个
updateInterval选项仅在Node.js环境中得到支持.
const client = await FliptClient.init({
namespace: 'default',
url: 'http://localhost:8080',
updateInterval: 30 // refresh every 30 seconds
});
一定要打电话给 close 方法 FliptClient 类,一旦您使用它来停止计时器(或关闭流)并清理资源.
client.close();
流程(服务生活动)
而不是投票,客户端可以实时接收国旗州更新 服务器事件。当服务器发出变化信号时,客户端会调试旗下状态,而且每一次流重联时,都不会错过更新.
import { FliptClient, FetchMode } from '@flipt-io/flipt-client-js';
const client = await FliptClient.init({
url: 'http://localhost:8080',
fetchMode: FetchMode.Streaming,
logger: console // optional
});
[注]
- 在流线模式
updateInterval被忽略,没有开始投票计时.- 浏览器 : 当地人
EventSource无法发送自定义信头, 因此authentication不适用于溪流。 使用基于 cookie 的认证或不需要对流端进行认证的 Flipt 服务器 .- 节点.js: 流线使用
eventsource软件包。 认证信头随流请求一同发送 .EventSource在瞬间出错后自动重新连接。 如果永久关闭连接, 客户端登录出错( 通过logger)并不断为最后已知的旗国服务.
打电话 close() 当客户端结束关闭流时.
状态更新听众
客户端可以告诉你国旗州变后,这样就可以重新读取所关心的国旗. 要求听众通过自动更新、流线或手册进行修改 refresh()。 。 。 .
创建客户端时注册一个收听器 :
const client = await FliptClient.init({
url: 'http://localhost:8080',
fetchMode: FetchMode.Streaming,
onStateUpdate: refreshFlags
});
或客户端运行时添加并删除听众 :
const unsubscribe = client.addStateUpdateListener(refreshFlags);
// Later, to stop listening:
unsubscribe();
听众的行为:
- 只有真正的变化. 在客户端应用不同于当前状态的旗帜状态后,会调用听众. 未更改的获取和重复的流传信件不称为它,以及
refresh()返回时false为了他们. - 不唤作起初相. 装入的状态
init不触发一个听众。 注册时读取您需要的旗帜 . - 错误不会触发它. 失败的抓取不调用听众 .
- 顺序,同步. 收听者按照被添加的顺序运行,就在新州被应用后. 听众可以评估旗帜、添加或删除听众或打电话
close()。 。 。 . - 例外情况已记录在案. 一个听众的例外被记录
logger.error不要阻止别人. - 之后什么都没有
close()。 。 。 . 后面没有听众close()。 。 。 .
ETag 支持
默认取取器使用 Etag HTTP 标题 以减少向 Flipt 实例提出的请求数量。 在旗下状态不经常更新且您想要减少服务器上负载的情景中,这很有用.
要禁用ETag 支持, 您可以执行 自定义获取器 不使用ETags.
Slim 模块
这个 slim 模块是针对高级或非标准环境设计的,其中您需要完全控制WASM 二进制的加载方式。 与试图自动加载WASM文件的默认客户端不同,瘦客户端要求您明确提供WASM文件(作为URL,缓冲等).
为什么要用瘦模组?
- 边缘/无服务/海关环境: 一些平台(如Cloudflare Workers,Vercel Edge,或某些节点.js设置)限制文件被加载或捆绑的方式. 瘦客户端允许您以适合您环境的方式加载WASM文件.
- 全控 : 您决定 WASM 文件的加载方式和时间 — 从 CDN 拖放、 从磁盘加载或使用自定义加载器 .
- 兼容性 : 瘦客户端去除了WASM加载的所有假设,使其与任何可以提供WASM二进制的环境相兼容.
- 套装大小 : 微弱的构造可能排除了与WASM加载相关的一些代码,使得它更轻而易举,更能为某些用法所动摇.
如果您正在使用带有捆绑器的标准浏览器应用程序,默认客户端通常更容易. 对于边缘,没有服务器,或自定义设置,瘦客户端是合适的工具.
使用 @flipt-io/flipt-client-js/slim 模块
这个 slim fliptClient的构建是为您想要提供自己的WASM 二进制的环境而设计的,比如现代浏览器(带有捆绑器)或Node.js.
浏览器用法( 带有类似 Vite, Webpack等的 Bundler)
-
导入并初始化客户端 :
import { FliptClient } from '@flipt-io/flipt-client-js/slim'; import wasmUrl from '@flipt-io/flipt-client-js/engine.wasm'; async function main() { const client = await FliptClient.init( { namespace: 'default', url: 'http://localhost:8080' }, { wasm: wasmUrl } ); // Use the client as normal const result = client.evaluateBoolean({ flagKey: 'my-flag', entityId: 'user-123', context: { country: 'US' } }); console.log(result); } main(); -
确保您的捆绑器配置为处理
.wasm文档.- 对于Vite,这个工作出了盒子.
- 对于Webpack,您可能需要添加一条规则:
.wasm文档.
节点使用
-
导入并初始化客户端 :
import { FliptClient } from '@flipt-io/flipt-client-js/slim'; import { readFileSync } from 'fs'; import path from 'path'; import { fileURLToPath } from 'url'; // Resolve the path to the WASM file const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const wasmPath = path.join( __dirname, '../node_modules/@flipt-io/flipt-client-js/engine.wasm' ); const wasmBuffer = readFileSync(wasmPath); async function main() { const client = await FliptClient.init( { namespace: 'default', url: 'http://localhost:8080' }, { wasm: wasmBuffer } ); // Use the client as normal const result = client.evaluateBoolean({ flagKey: 'my-flag', entityId: 'user-123', context: { country: 'US' } }); console.log(result); } main();- 说明: 在Node.js中,您必须使用 WASM 文件作为缓冲器加载
fs.readFileSync。 。 。 .
- 说明: 在Node.js中,您必须使用 WASM 文件作为缓冲器加载
-
用一个支持无害环境管理和顶级等待的加载器运行您的脚本, 例如
ts-node或者说tsx数字 :npx tsx src/index.ts
补充说明
- 这个
slim构建需要您通过wasm选项. - 对于浏览器的使用,将 URL 传递到 WASM 文件(使用您捆绑器的资产处理) .
- 对于Node.js,通过WASM文件作为缓冲.
- 确保您的环境支持顶级
await或将代码包入同步函数中.
发展
刚才
这个库使用WebAssem(WASM)层与Flipt服务器交互. 它用 Rust 写成,并使用 wasm-bindgen 财务报告和审定财务报表 wasm-pack 工具。 我们用JavaScript API将已建成的WASM层包裹起来,以便于在网络环境中使用.
先决条件
构建
npm run build
测试
npm install
npm test
捐款
欢迎捐款! 请随意打开一个问题或提交拉出请求.
许可证
本项目根据以下规定获得许可证: MIT 许可证。 。 。 .