# @bucketeer/openfeature-node-server-sdk 中文文档

规范地址：https://npmcn.com/package/%40bucketeer/openfeature-node-server-sdk/

版本：0\.0\.3
npm 元数据更新时间：2026-08-07T12:18:16.388Z
中文译文更新时间：2026-11-08T18:00:42.941Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bucketeer/openfeature-node-server-sdk
原文对照：https://npmcn.com/package/%40bucketeer/openfeature-node-server-sdk/?lang=original
项目主页：https://github.com/bucketeer-io/openfeature-node-server-sdk#readme
源码仓库：https://github.com/bucketeer-io/openfeature-node-server-sdk

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

- 包体积（解压后）：117 kB，45 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@bucketeer/node-server-sdk ^0\.4\.5，@openfeature/server-sdk ^1\.19\.0
- 首次发布：2025-11-21T08:02:20.563Z
- 最新版本发布：2026-08-07T12:18:16.093Z
- 近 30 天下载量：10272（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

这是正式的 Node.js 服务器端 OpenFeature 供应商,用于访问您的功能旗 [巴克特尔](https://bucketeer.io/)。 。 。 .

## 安装

```sh
npm install @bucketeer/openfeature-node-server-sdk
```

也可以使用：`pnpm add @bucketeer/openfeature-node-server-sdk`、`yarn add @bucketeer/openfeature-node-server-sdk`、`bun add @bucketeer/openfeature-node-server-sdk`

## README

# Bucketeer - OpenFeature Node.js 服务器提供商

这是正式的 Node.js 服务器端 OpenFeature 供应商,用于访问您的功能旗 [巴克特尔](https://bucketeer.io/)。 。 。 .

[巴克特尔](https://bucketeer.io/) 是一个开源平台,由 [网络代理商](https://www.cyberagent.co.jp/en/) 帮助各小组作出更好的决定,减少部署准备时间,并通过特征旗帜释放风险。 Bucketeer提供先进的功能,如暗发射和相继推出,根据用户属性,设备,以及其他部分进行有限的发布.

与 [OpenFeature 服务器 SDK](https://openfeature.dev/docs/reference/concepts/provider) 您可以在节点服务器应用程序中评估您的特性标记.

> \[尖叫声\] 这是一个β版本。 在一般发布前可以引入中断更改.

有关巴克特尔旗帜管理的文件,参见 [巴克特文档网站](https://docs.bucketeer.io/sdk/server-side/node-js)。 。 。 .

## 安装

```bash
npm install @bucketeer/openfeature-node-server-sdk @openfeature/server-sdk @bucketeer/node-server-sdk @openfeature/core
```

**说明:** 此软件包需要 `@openfeature/server-sdk` 财务报告和审定财务报表 `@bucketeer/node-server-sdk` 作为同伴的依赖关系.

`@openfeature/server-sdk` 需求 `@openfeature/core` 作为同伴的依赖.

## 使用量

### 初始化提供者

Bucketeer 提供者需要创建,然后设置在全球 OpenFeature 实例中.

```typescript
import { OpenFeature } from '@openfeature/server-sdk';
import { BucketeerProvider, defineBKTConfig } from '@bucketeer/openfeature-node-server-sdk';

const config = defineBKTConfig({
  apiKey: 'BUCKETEER_API_KEY',
  apiEndpoint: 'BUCKETEER_API_ENDPOINT',
  featureTag: 'FEATURE_TAG',
  appVersion: '1.2.3',
});

// Initialize the provider
const provider = new BucketeerProvider(config);

// Set the provider and wait for initialization
await OpenFeature.setProviderAndWait(provider);
```

看我们的 [文档](https://docs.bucketeer.io/sdk/server-side/node-js) 用于更多的 SDK 配置选项.

评价上下文允许客户端指定Bucketeer用来评价特征旗的上下文数据.

这个 `targetingKey` 是用户ID(唯一ID),不能为空.

### 评价背景

在服务器侧应用程序中,评价背景通常按请求提供,而不是全球设定。 这使得用户可以根据请求的数据进行特定旗帜的评价.

```typescript
const client = OpenFeature.getClient();

// Define evaluation context per request/user
const evaluationContext = {
  targetingKey: 'user-123', // Required: unique user identifier
  email: 'user@example.com', // User attributes for targeting
  plan: 'premium',
  region: 'us-east-1',
  timestamp: new Date().toISOString(),
};

// Evaluate flags with context
const featureEnabled = await client.getBooleanValue('new-feature', false, evaluationContext);
```

对于需要在所有评价中共享一些共同上下文的应用程序,可以设置客户级上下文:

```typescript
const client = OpenFeature.getClient();

// Set common context at the client level (e.g., application version)
client.setContext({
  version: process.env.APP_VERSION,
  environment: process.env.NODE_ENV,
});

// Per-request context will be merged with client context
const requestContext = {
  targetingKey: req.user.id,
  email: req.user.email,
  plan: req.user.plan,
};

const result = await client.getBooleanValue('feature-flag', false, requestContext);
```

### 评估特征旗

在提供者设置并准备好之后,您可以使用 OpenFeature 客户端来评价特征标记. 总是为每项评价提供评价背景.

```typescript
const client = OpenFeature.getClient();

// Define evaluation context (typically per request)
const context = {
  targetingKey: 'user-123', // Required
  email: 'user@example.com',
  plan: 'premium',
};

// boolean flag
const booleanValue = await client.getBooleanValue('my-feature-flag', false, context);

// string flag
const stringValue = await client.getStringValue('my-feature-flag', 'default-value', context);

// number flag
const numberValue = await client.getNumberValue('my-feature-flag', 0, context);

// object flag
const objectValue = await client.getObjectValue('my-feature-flag', {}, context);

// Get detailed evaluation results
const booleanDetails = await client.getBooleanDetails('my-feature-flag', false, context);
console.log(booleanDetails.value, booleanDetails.reason, booleanDetails.variant);
```

### Express.js 示例

以下是您在 Express.js 应用程序中如何使用这个 :

```typescript
import express from 'express';
import { OpenFeature } from '@openfeature/server-sdk';
import { BucketeerProvider, defineBKTConfig } from '@bucketeer/openfeature-node-server-sdk';

const app = express();
const client = OpenFeature.getClient();

app.get('/api/features', async (req, res) => {
  // Create evaluation context from request
  // In a real app, you'd get the user ID from your auth system
  const userId = (req.headers['x-user-id'] as string) || 'anonymous';
  const userEmail = req.headers['x-user-email'] as string;

  const context = {
    targetingKey: userId,
    email: userEmail,
    userAgent: req.get('User-Agent'),
    ipAddress: req.ip,
  };

  try {
    const features = {
      newDashboard: await client.getBooleanValue('new-dashboard', false, context),
      welcomeMessage: await client.getStringValue('welcome-message', 'Welcome!', context),
      maxItems: await client.getNumberValue('max-items-per-page', 10, context),
    };

    res.json(features);
  } catch (error) {
    console.error('Feature flag evaluation error:', error);
    res.status(500).json({ error: 'Failed to evaluate features' });
  }
});

// Alternative example with authentication middleware
interface AuthenticatedRequest extends express.Request {
  user?: {
    id: string;
    email: string;
    plan: string;
  };
}

app.get('/api/user-features', async (req: AuthenticatedRequest, res) => {
  // Assuming you have authentication middleware that sets req.user
  const context = {
    targetingKey: req.user?.id || 'anonymous',
    email: req.user?.email,
    plan: req.user?.plan || 'free',
    userAgent: req.get('User-Agent'),
    ipAddress: req.ip,
  };

  try {
    const features = {
      premiumFeature: await client.getBooleanValue('premium-feature', false, context),
      dashboardTheme: await client.getStringValue('dashboard-theme', 'default', context),
    };

    res.json(features);
  } catch (error) {
    console.error('Feature flag evaluation error:', error);
    res.status(500).json({ error: 'Failed to evaluate features' });
  }
});
```

### 完整示例

以下是如何使用 Bucketeer OpenFeature Node.js 服务器供应商的完整实例:

```typescript
import { OpenFeature } from '@openfeature/server-sdk';
import { BucketeerProvider, defineBKTConfig } from '@bucketeer/openfeature-node-server-sdk';

async function main() {
  try {
    // Configure Bucketeer
    const config = defineBKTConfig({
      apiKey: process.env.BUCKETEER_API_KEY!,
      apiEndpoint: process.env.BUCKETEER_API_ENDPOINT!,
      featureTag: process.env.BUCKETEER_FEATURE_TAG!,
      appVersion: '1.0.0',
    });

    // Initialize provider with optional timeout
    const provider = new BucketeerProvider(config, {
      initializationTimeoutMs: 30000, // 30 seconds
    });

    // Set provider and wait for initialization
    await OpenFeature.setProviderAndWait(provider);

    // Get client
    const client = OpenFeature.getClient('my-app');

    // Simulate user request - define evaluation context per user/request
    const userContext = {
      targetingKey: 'user-123',
      email: 'user@example.com',
      plan: 'premium',
      timestamp: new Date().toISOString(),
    };

    // Evaluate feature flags with context
    const isNewFeatureEnabled = await client.getBooleanValue('new-feature', false, userContext);
    const welcomeMessage = await client.getStringValue('welcome-message', 'Welcome!', userContext);
    const maxItems = await client.getNumberValue('max-items', 10, userContext);

    console.log(`New feature enabled: ${isNewFeatureEnabled}`);
    console.log(`Welcome message: ${welcomeMessage}`);
    console.log(`Max items: ${maxItems}`);

    // Example of different user context
    const anotherUserContext = {
      targetingKey: 'user-456',
      email: 'another@example.com',
      plan: 'free',
    };

    const featureForAnotherUser = await client.getBooleanValue(
      'new-feature',
      false,
      anotherUserContext,
    );
    console.log(`Feature for another user: ${featureForAnotherUser}`);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Clean up when your application shuts down
    await OpenFeature.close();
  }
}

main();
```

## 捐款

我们会为你贡献给巴克特 并帮助改善它! 任何人都可以使用和享受它!

请遵照我们的贡献指南 [这里](https://docs.bucketeer.io/contribution-guide/)。 。 。 .

## 发展

### 环境

-   节点.js
    -   检查 `./.nvmrc` 所需的版本
-   线条
    -   软件包管理器

你需要一个 `.env` 为测试提供 API 机密的文件. 复制 `.env.example` 并重命名为 `.env`,然后用你的巴克特证书更新它.

### 图标

```bash
# Install dependencies
yarn install

# Build the project
yarn build

# Run tests
yarn test

# Run end-to-end tests
yarn test:e2e

# Lint code
yarn lint

# Format code
yarn prettier:fix
```

### 示例应用程序

检查 `example/` 一个完整的Express.js应用程序的目录,演示如何使用此SDK.

```bash
cd example
npm install
npm run build
npm run dev
```

## 许可证

Apache 许可证 2.0, 见 [自由主义](https://github.com/bucketeer-io/openfeature-node-server-sdk/blob/main/LICENSE)。 。 。 .

## 常见问题

### @bucketeer/openfeature-node-server-sdk 是什么？

这是正式的 Node\.js 服务器端 OpenFeature 供应商,用于访问您的功能旗 巴克特尔。 。 。 \.

### 如何安装 @bucketeer/openfeature-node-server-sdk？

在项目目录运行 npm install @bucketeer/openfeature-node-server-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bucketeer/node-server-sdk（^0\.4\.5）、@openfeature/server-sdk（^1\.19\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bucketeer/openfeature-node-server-sdk 支持 TypeScript 吗？

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

### @bucketeer/openfeature-node-server-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bucketeer/openfeature-node-server-sdk 可以商用吗？

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

### @bucketeer/openfeature-node-server-sdk 的下载量有多少？

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

### @bucketeer/openfeature-node-server-sdk 还在维护吗？

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