@harnessio/ff-javascript-client-sdk

中文文档
1.32.0发布于 2025/12/23Apache-2.0TypeScriptESM + CJS近 30 天下载 13.7万

基本库用于将CF整合到javascript应用中.

中文使用文档
文档目录18 节
  1. 安装
  2. 使用量
  3. 流和投票模式
  4. 流线模式
  5. 投票模式
  6. 不流出或投票
  7. 最大流调试
  8. 听从事件 client 举个例子.
  9. 获取特定特性旗的值
  10. 清理
  11. 缓存
  12. 设定评价
  13. 认证请求超时
  14. API 中间软件
  15. 日志
  16. 从 unpkg 直接导入
  17. 进一步阅读
  18. 许可证

在你开始之前

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” 不存在, 变化 值将是此处提供的默认值
  • 注意返回默认变量的原因可以是:
    1. SDK 尚未初始化
    2. 旗帜标识符中的 Typo
    3. 使用错误的工程 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版 (英语).

版本与发布记录

@harnessio/ff-javascript-client-sdk 共发布 128 个版本,首次发布于 2021/03/10;过去 12 个月发布了 2 个版本。

版本发布日期距今
1.32.0latest2025/12/2310 个月前
1.31.32025/11/2811 个月前
1.31.22025/08/201.2 年前
1.31.12025/08/181.2 年前
1.31.02025/04/041.6 年前
1.30.02025/02/071.8 年前

其他发布通道:alpha → 1.24.0-alpha.1,beta → 1.29.0-rc.1。

关于 @harnessio/ff-javascript-client-sdk 的常见问题

@harnessio/ff-javascript-client-sdk 是什么?

基本库用于将CF整合到javascript应用中.

如何安装 @harnessio/ff-javascript-client-sdk?

在项目目录运行 npm install @harnessio/ff-javascript-client-sdk,或使用 pnpm add / yarn add / bun add。

@harnessio/ff-javascript-client-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@harnessio/ff-javascript-client-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@harnessio/ff-javascript-client-sdk 可以商用吗?

@harnessio/ff-javascript-client-sdk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@harnessio/ff-javascript-client-sdk 的下载量有多少?

根据 npm 官方下载统计,@harnessio/ff-javascript-client-sdk 在 2026/10/18 – 2026/11/16 这 30 天内被下载 136,775 次,日均约 4,559 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@harnessio/ff-javascript-client-sdk 还在维护吗?

最新版本 1.32.0 发布于 2025/12/23(10 个月前);至今共发布 128 个版本,其中过去 12 个月发布了 2 个;首次发布于 2021/03/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。