TypeScript Server SDK

FlagshipServerProvider 实现了 OpenFeature 服务器提供商接口。该提供商适用于 Cloudflare Workers、Node.js 以及任何支持 Fetch API 的服务器端 JavaScript 运行时。

在 Cloudflare Worker 内部，您可以将 Flagship 绑定直接传递给提供商。这避免了 HTTP 开销，并且也是推荐的方法。在 Workers 之外，请使用应用 ID 和账户 ID 初始化提供商。

设置

直接将 Flagship 绑定传递给提供商。这是在 Worker 内部推荐的方法。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request, env) {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42", plan: "enterprise" },
		);

		if (showNewCheckout) {
			return new Response("New checkout enabled!");
		}

		return new Response("Standard checkout.");
	},
};

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42", plan: "enterprise" },
		);

		if (showNewCheckout) {
			return new Response("New checkout enabled!");
		}

		return new Response("Standard checkout.");
	},
};

当在 Worker 之外（例如在 Node.js 中）运行时，请使用应用 ID、账户 ID 和 API 令牌。从您的 Cloudflare 账户生成一个具有 Flagship 读取权限的 API 令牌。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
});

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
});

配置选项

Option	Type	Required	Description
`binding`	`Flagship`	No	来自 `env.FLAGS` 的 Flagship 绑定。在 Worker 内部使用它以获得最佳性能。绑定会自动处理身份验证。
`appId`	`string`	No	Cloudflare 仪表板中的 Flagship 应用 ID。如果不使用绑定则为必需。
`accountId`	`string`	No	您的 Cloudflare 账户 ID。当使用 `appId` 时为必需。
`authToken`	`string`	No	具有 Flagship 读取权限的 Cloudflare API 令牌。如果不使用绑定则为必需。
`fetchOptions`	`RequestInit`	No	应用于 HTTP 请求的自定义 fetch 选项。
`timeout`	`number`	No	请求超时时间，单位为毫秒。默认为 `5000`。
`retries`	`number`	No	发生临时错误时的重试次数。默认为 `1`，最高上限为 `10`。
`retryDelay`	`number`	No	重试之间的延迟时间，单位为毫秒。默认为 `1000`，最高上限为 `30000`。
`cacheTtl`	`number`	No	缓存 TTL，单位为毫秒。当大于 `0` 时启用响应缓存。
`cacheMaxSize`	`number`	No	最大缓存条目数。当设置了 `cacheTtl` 时，默认为 `1000`。

请提供 binding，或者提供 appId、accountId 和 authToken。

响应缓存

服务器端响应缓存默认是关闭的。当您希望具有相同标志、类型和评估上下文的重复评估能重用最近的结果时，请使用 cacheTtl 启用它。

new FlagshipServerProvider({
	appId: "<APP_ID>",
	accountId: "<ACCOUNT_ID>",
	authToken: "<API_TOKEN>",
	cacheTtl: 30_000,
	cacheMaxSize: 1000,
});

在相同上下文中重复评估相同标志的高流量服务器应用程序中，请使用缓存。在 TTL 过期之前，缓存的值可能是过时的，因此对于那些您期望在活动推出期间更改的标志，请保持较短的 TTL。提供商不缓存禁用的标志或错误。

评估上下文

OpenFeature 使用评估上下文将用户属性传递给标志提供商。targetingKey 字段是主要的用户标识符。

在 targetingKey 旁边传递其他属性以匹配目标规则。例如，您可以包含 plan、country，或您的规则引用的任何自定义属性。

使用诸如字符串、数字、布尔值和 Date 对象之类的基本上下文值。提供商会拒绝将对象和数组作为无效上下文。

const value = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
	country: "US",
});

const value = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
	country: "US",
});

可用钩子

该 SDK 附带了两个钩子 (hooks)，您可以将它们附加到 OpenFeature 客户端。

LoggingHook — 记录每次评估的结构化信息。
TelemetryHook — 捕获计时和事件数据以用于可观测性。

import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";

OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());

import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";

OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());

从其他提供商迁移

如果您使用了其他兼容 OpenFeature 的提供商（例如 LaunchDarkly 或 Flagsmith），请通过替换提供商初始化来切换到 Flagship。在评估调用点无需进行任何更改。

// Before
await OpenFeature.setProviderAndWait(
	new LaunchDarklyProvider({ sdkKey: "..." }),
);

// After
await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

// Before
await OpenFeature.setProviderAndWait(
	new LaunchDarklyProvider({ sdkKey: "..." }),
);

// After
await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);