# @atlaskit/flag-client 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/flag-client/

版本：1\.0\.3
npm 元数据更新时间：2026-11-02T05:45:12.393Z
中文译文更新时间：2026-11-07T02:55:14.629Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/flag-client
原文对照：https://npmcn.com/package/%40atlaskit/flag-client/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：443 kB，90 个文件
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2026-10-26T09:30:51.199Z
- 最新版本发布：2026-11-02T05:45:12.149Z
- 近 30 天下载量：29145（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

浏览器-安全 JavaScript 客户端用于从 Feature Flag 平台读取服务器评价的功能旗.

## 安装

```sh
npm install @atlaskit/flag-client
```

也可以使用：`pnpm add @atlaskit/flag-client`、`yarn add @atlaskit/flag-client`、`bun add @atlaskit/flag-client`

## README

# @atlaskit/旗下客户

浏览器- 安全 JavaScript 客户端, 用于从服务器读取评价过的特性旗 `BulkEvaluationPayload`。 。 。 .

客户端不会在当地获取,投票,订阅或评价国旗规则. 打电话者,通常 `@atlaskit/feature-gate-js-client` 包装器,获得有效载荷(从地物旗帜服务处获得) `/evalFlags` 响应或服务器的靴子),并通过一个 同步供养.

这个包是FFPJavaScript客户端. 在阿特拉斯前端维持 单相机。 其行为由 `client-js-*` 能力 [`openspec/specs/`](https://bitbucket.org/atlassian/feature-flag-platform/src/main/openspec/specs/) 输入 `feature-flag-platform` 仓库.

## 安装和导入

```bash
yarn add @atlaskit/flag-client
```

```ts
import { FlagClient } from '@atlaskit/flag-client/client';
import type { BulkEvaluationPayload, FlagUser } from '@atlaskit/flag-client/types';
```

## 有效载荷形状

`BulkEvaluationPayload`,供应商返回的,是有效载荷电线格式的结合 客户支持, 受到歧视 `vs`它目前有一个成员, `BulkEvaluationPayloadV1`A级 未来计划版本的外形可能完全不同 并且将永远带着它 `vs`。 。 。 .

A 类 `BulkEvaluationPayloadV1` 是对象有:

-   `vs` (可选):有效载荷计划版本. 唯一支持的版本是 `"1"`和缺席 `vs` 被视为 `"1"`。没有 `vs` 与原载相同的有效载荷 `vs: "1"` 生成相同的旗帜值并详细列出元数据。 任何其他价值,包括 `null` 或 编号 `1`,未初始化或替换为 `invalid_schema_version` 在其他时间之前 有效载荷被验证.
-   `flags` (所需):a `BulkEvaluationResult`,将每个旗帜键映射为 a `FlagResult`。 。 形状匹配 `flags` 地物旗务局成员 `ffp` 载荷。 也许是空的.
-   `requestContext` (要求):对有效载荷的识别特征和属性进行了评估。 它必须 成型良好,但客户端不使用它来读取或细节. 没有它的有效载荷失败 与 `invalid_payload_shape`。 。 `attributes` 可选和缺勤 `attributes` 保留 作为 `{}`页:1 `null` `attributes` 以 `invalid_payload_shape`。 。 。 .
-   `clientVersion` (可选):旗下数据版本,, `{ token, updatedAt? }`,匹配 地物旗帜服务 `FfpBootstrapPayload.ClientVersion`。当存在时, `token` 一定是个 非空字符串和 `updatedAt` 一个字符串。 客户把它和有效载荷放在一起,换上 `replace`,而不用于读取或细节.

A 类 `null` `requestContext` 或者说 `clientVersion` 无效。 其他有效载荷成员,例如: `status` 或者说 `targetApp`,被忽略,所以一个 `ffp` 对象可以作为-is通过。 旗下未知成员 结果及其元数据也被忽视.

此输入与服务器 SDK 有意不同 `BulkEvaluationPayload` 说明 [`sdks/README.md`](https://bitbucket.org/atlassian/feature-flag-platform/src/main/sdks/README.md)数字 : 它没有有效载荷水平 `status`。 。 。 .

每个旗帜结果的元数据也可能携带 `holdoutAllocation`, (中文(简体) ), `segments`, (中文(简体) ), `targetApps`, (中文(简体) ), `flagVersion`,以及 `errorMessage`。当它们出现时,它们必须是物体或 `null`,以 对象、字符串、字符串和字符串。 A 类 `holdoutAllocations` 列表从 年长的制片人被忽略了.

## 初始化

每个目标应用和环境构建一个客户端,然后初始化. 初始化为 同步,每个客户实例一次性,永不抛出.

```ts
const client = new FlagClient({
    targetApp: 'jira-frontend',
    environmentType: 'prod', // 'dev' | 'local' | 'staging' | 'prod'
    serviceVersion: appVersion, // optional
});
const user: FlagUser = {
    identifiers: { atlassianAccountId: accountId },
    attributes: { plan: 'premium' }, // optional
};

const init = client.initialize(() => payload, user);

if (!init.initialized) {
    // Reads return safe defaults. The SDK logs the failure reason and a troubleshooting tip.
}
```

-   构造器选项为实例的寿命设定 . `targetApp` 财务报告和审定财务报表 `environmentType` 需要并且 `serviceVersion` 是可选的。 客户端在未验证的情况下复制 运行时间,在施工期间从不投掷,也不用于阅读. 他们识别 客户端在曝光遥测.
-   只有在 `initialize` 或者说 `replace`。客户端保持不可改变 它返回的有效载荷的快照.
-   失败的原因是 `already_initialized`, (中文(简体) ), `provider_threw`, (中文(简体) ), `provider_returned_no_payload`, (中文(简体) ), `invalid_schema_version`, (中文(简体) ), `invalid_payload_shape`,以及 `payload_capture_failed`失败 初始化,不包括 `already_initialized`,可以重审.

### 用户

存储时, 用户将正常化为被冻结的副本 :

-   非字符串的标识符值被丢弃 .
-   属性值不是字符串、布尔斯或有限数字被丢弃.
-   一个用户, `identifiers`,或 `attributes` 非对象成员被视为空。 选择 `attributes` 等同为 `{}`。 。 。 .

常态化从不失败初始化或替换,空的标识符映射是有效的. 何时 sDK记录一 `console.warn(...)` 每个呼叫中, 给丢的密钥起名, 但是 从来没有他们的价值观.

客户端将常态化用户从每次初始化尝试中保留下来,但 `already_initialized`,包括一个失败, 因此曝光遥测可以属性读取 在初始化成功之前.

## 替换有效载荷和用户

使用 `replace` 当用户更改时。 它将有效载荷和用户互换;构建器选项 不变.

```ts
const outcome = client.replace(() => nextPayload, nextUser);

if (!outcome.replaced) {
    // The previous payload and user are still served.
}
```

`replace` 失败 `not_initialized`,没有援引提供者,直到 `initialize` 已经 成功 。 其其他故障原因与初始化供应商和有效载荷原因相匹配. 任何失败 替换可以保持先前的有效载荷和用户,SDK记录原因和提示.

## 读取值和细节

输入值读取当有效载荷能为请求的旗帜服务时返回已初始化的旗帜值 和类型。 否则,他们将归还提供的安全违约.

```ts
const enabled = client.getBooleanValue('admin-toolbar.enabled', false);
const label = client.getStringValue('button.label', 'Continue');
const maxResults = client.getNumberValue('search.max-results', 25);
const config = client.getObjectValue('ui.config', { density: 'comfortable' });
```

细节读取返回请求旗的相同选定值和元数据.

```ts
const details = client.getBooleanDetails('admin-toolbar.enabled', false);

console.log(details.value);
console.log(details.metadata.matchReason);
console.log(details.metadata.identifierValue); // from the current user
console.log(details.metadata.holdoutAllocation);
```

`identifierValue` 在使用结果的当前用户标识符中查找 `identifierType`,从来没有在有效载荷 `requestContext`。 。 。 . `holdoutAllocation` 是结果 分配,或 `null` 缺席时,和 `segments` 是结果的列表,或者当 缺席. `targetApps`, (中文(简体) ), `flagVersion`,以及 `errorMessage` 内部保留,不属于 细节元数据.

## 安全默认和代码默认

客户端返回未初始化时的安全默认值, 旗帜缺失, 请求读取 类型不匹配旗下结果,运行时值形状无法使用,或者结果有 `useCodeDefault = true`。 。 。 .

对于 `useCodeDefault = true`,细节读取仍然保留服务器元数据 从有效载荷。 其它 后退大小写使用客户端生成的元数据 : `not_initialized`, (中文(简体) ), `flag_not_found`,或 `type_mismatch`。 。 。 .

## 对象和数组值

从初始有效载荷状态中选择的对象和阵列值来自客户端的不可改变性 载荷快照。 相对于已回回的初始值的变异尝试不会在以后改变 读取或详细说明元数据。 将返回的对象或阵列克隆在应用代码中变异之前 .

安全默认值由呼叫者提供返回.

## 曝光遥测

在浏览器中,每个输入的值或细节都会记录一次曝光: OpenTeleometry 日志记录在 共享接触计划(`sdks/design/otel-exposure-event-schema.md` 在地标-旗-平面图中 存储器). 客户端批量曝光并张贴为OTLP/JSON到旗下遥测.

仅在全局时默认进行曝光记录 `window` 在建筑中存在。 在节点和 SSR 关闭,除非 `enabled: true` 通过。 DOM 测试环境,如 jsdom 和 幸福度 定义 `window`,所以通过 `enabled: false` 不得在接触后进行试验。 配置为 页:1 `exposureLogging` 构造器选项 :

```ts
const client = new FlagClient({
    targetApp: 'jira-frontend',
    environmentType: 'prod',
    exposureLogging: {
        enabled: true, // default: whether a global `window` exists
        endpoint: 'https://xp.atlassian.com/ft/v1/logs', // default; or a same-origin path
        batchSize: 100, // default: exposures that trigger an immediate delivery
        flushIntervalMs: 10_000, // default: how long a queued exposure waits
    },
});
```

失败的选项, 例如 `batchSize: 0`, (中文(简体) ), `endpoint: 'relative/path'`,或一个 `endpoint` 带有用户名或密码的 URL 被忽略: 它的默认适用,客户端写一个 `console.warn` 命名选项,绝不是其值。 建筑从不扔. 残疾客户端确实如此 未检查 `endpoint`, (中文(简体) ), `batchSize`,或 `flushIntervalMs` 将一个配置传递给两个 浏览器和SSR客户端很安静.

### 什么样的暴露

-   `service.name` 财务报告和审定财务报表 `feature_flag.set.id` 来自 `targetApp`。 。 。 . `deployment.environment_type` 财务报告和审定财务报表 `deployment.environment.name` 来自 `environmentType`,以及 `service.version` 从 `serviceVersion`。 。 。 .
-   仪器范围名称和 `atl.feature_flag.sdk.type` 为: `@atlaskit/flag-client`,则 范围版本是这个包的版本.
-   识别器和属性来自持有的有效载荷 `requestContext`。当客户持有 没有有效载荷,它们来自当前用户,在失败后 `initialize` 用户通过 对它。 细节 `identifierValue` 总是来自当前用户.
-   `atl.feature_flag.result.source` 实值 `bootstrap` 当读取时,客户端持有 初始有效载荷,包括用于 `flag_not_found` 财务报告和审定财务报表 `type_mismatch`,以及 `fallback` 改为: 成功前制作的 `initialize`,即使当 `logExposure` 后回放时.
-   错误原因( E)`not_initialized`, (中文(简体) ), `flag_not_found`, (中文(简体) ), `type_mismatch`, (中文(简体) ), `general_error`,以及 `invalid_context`)不带变体或规则,其错误消息从 `FFP evaluation failed: <reason>`。 。 。 . `general_error` 财务报告和审定财务报表 `invalid_context` 使用有效载荷 `errorMessage` 换成 当它不空虚的时候。 A 类 `not_initialized` 信件以原因结尾, 例如 `(no initialize attempt completed)` 或最近失败的原因.
-   `type_mismatch` 保留有效载荷旗的版本和目标应用.
-   拒绝分配成为 `atl.feature_flag.holdout_allocation.*` 属性 `holdoutKey`, (中文(简体) ), `identifierType`,以及 `allocationReason` 是字符串,与 `holdout_rule_id` 仅限 用于字符串 `holdoutRuleId`否则,所有四个都省略.

### 人工禁止和记录

过 `{ disableExposureLogging: true }` 以跳过自动曝光。 记录一 稍后, 例如,当用户实际看到该特性时 `logExposure`数字 :

```ts
const details = client.getBooleanDetails('new-nav.enabled', false, {
    disableExposureLogging: true,
});
// ...later, when the navigation is rendered:
client.logExposure(details);
```

详细信息,这个客户端 返回,包括浅拷贝, `logExposure` 记录曝光 读本会制作,标记手册,即使以后 `initialize` 或者说 `replace`详细情况 客户端没有返回, 如从 JSON 重建的客户端, 使用调用时的客户端状态 。 这个 当曝光记录被禁用时, 永不丢弃,也不做任何事情.

### 重复、交付和持久性

-   与队列相同的旗下密钥、变异、规则、匹配理由和标识符曝光 在最后的10分钟 被丢弃。 手动和自动曝光共用这些窗口。 A 类 已经成功 `replace` 结束这一切.
-   一个请求是一次飞来飞去的 `credentials: 'omit'`。网络错误,请求不 30秒内就解决了, `429`,以及 `5xx` 状态在 1 秒后重审, 然后是 2 秒数。 任何其他非`2xx` 状态 :.
-   每个客户端都有一个断路器. 在连续三次可重试失败之后,它打开:曝光 保留队列,每60秒发送一个批次,检查端点是否 已经康复了 无法重试的第一个响应关闭它,队列被冲出. 可重试 失败从不减少接触,但从第一次可重试失败一直到交付得到任何 其它结果,客户端只保留了1000个最新曝光的内存.
-   当页面被隐藏时,未交付的曝光被保存到 `localStorage` 开始键下 `@atlaskit/flag-client:exposures:`,每次曝光的队列在隐藏时也会如此。 这个 由同一来源构建的下一个客户端 `endpoint`,以 保存它们的客户端已被配置 。 它一带他们就送他们去, 而不是之后 `flushIntervalMs`除非断路器挡住他们 存储出错 永远不要扔.
-   原产地的每个客户都分享 `localStorage` 131,072个UTF-16编码单位的预算(256 KiB), 包含密钥,并且只保存符合其最近曝光的密钥。 彼等受记. 那边 对节省的风险没有单独的限制;只有预算才能决定.
-   在成功交付后,客户记录时间 `@atlaskit/flag-client:last-delivery`最多一小时一次 交货失败时 过去7天没有记录到成功的源头,例如内容屏蔽器拒绝的源头 每个请求,预算是4,096个代码单元(8 KiB)取而代之.

### 同产和跨产

`endpoint` 也接受从单一开始的路径 `/`。客户端解决一次 建筑业 `window.location.origin`,所以一种产品,其来源路线与Flag相同 遥测完全避免了CORS,就像GASv3那样:

```ts
// Delivers to https://<product host>/gateway/api/ft/v1/logs
exposureLogging: { endpoint: '/gateway/api/ft/v1/logs' }
```

上面的路径是说明性的;使用您产品实际服务的路径. 路径被忽略 当启用客户端时警告 `window`,来源不透明,路径开始于 `//` 或者说 `/\`,或者它解决另一个来源.

没有路径,暴露于交叉来源处 `https://xp.atlassian.com/ft/v1/logs` 作为 `application/json`,这需要 CORS 预先飞行。 产品页面的交付取决于 那条航线会回答飞行前的问题.

## 发展

运行从 `platform/` 目录 :

```bash
afm test unit packages/measurement/flag-client
afm ts check --project ./packages/measurement/flag-client/tsconfig.app.json
afm lint eslint packages/measurement/flag-client
```

共享测试向量在 `src/__tests__/__fixtures__/` 由特性旗-平台销售 仓库 : `bulk-evaluation-fixtures.json` 从 `sdks/evaluation-test-vectors`,以及 `exposure-test-vectors/` (只有JSON文件)来自 `sdks/exposure-test-vectors`。当 共享固定装置的改变.

## 常见问题

### @atlaskit/flag-client 是什么？

浏览器-安全 JavaScript 客户端用于从 Feature Flag 平台读取服务器评价的功能旗\.

### 如何安装 @atlaskit/flag-client？

在项目目录运行 npm install @atlaskit/flag-client，或使用 pnpm add / yarn add / bun add。

### @atlaskit/flag-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/atlaskit\_\_flag-client 是否存在。

### @atlaskit/flag-client 可以商用吗？

@atlaskit/flag-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/flag-client 的下载量有多少？

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

### @atlaskit/flag-client 还在维护吗？

最新版本 1\.0\.3 发布于 2026/11/02（5 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/10/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。